home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / gnuish / ginf / texi.inf (.txt) < prev    next >
GNU Info File  |  1993-09-30  |  533KB  |  10,314 lines
  1. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2. file texi.texi.
  3.    This file documents Texinfo, a documentation system that uses a
  4. single source file to produce both on-line information and a printed
  5. manual.
  6.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  7.    This is the second edition of the Texinfo documentation,
  8. and is consistent with version 2 of `texinfo.tex'.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Free Software Foundation.
  20. Indirect:
  21. texi.info-1: 1096
  22. texi.info-2: 50585
  23. texi.info-3: 100344
  24. texi.info-4: 149083
  25. texi.info-5: 197497
  26. texi.info-6: 247275
  27. texi.info-7: 296490
  28. texi.info-8: 346023
  29. texi.info-9: 387598
  30. texi.info-10: 433598
  31. texi.info-11: 476101
  32. Tag Table:
  33. (Indirect)
  34. Node: Top
  35. Node: Copying
  36. 21758
  37. Node: Overview
  38. 23766
  39. Node: Using Texinfo
  40. 25673
  41. Node: Info Files
  42. 28165
  43. Node: Printed Books
  44. 32225
  45. Node: Formatting Commands
  46. 35110
  47. Node: Conventions
  48. 38551
  49. Node: Comments
  50. 40811
  51. Node: Minimum
  52. 42233
  53. Node: Six Parts
  54. 44386
  55. Node: Short Sample
  56. 45896
  57. Node: Acknowledgements
  58. 50027
  59. Node: Texinfo Mode
  60. 50585
  61. Node: Texinfo Mode Overview
  62. 51956
  63. Node: Emacs Editing
  64. 52709
  65. Node: Inserting
  66. 54839
  67. Node: Showing the Structure
  68. 59115
  69. Node: Updating Nodes and Menus
  70. 61634
  71. Node: Updating Commands
  72. 62706
  73. Node: Updating Requirements
  74. 68741
  75. Node: Other Updating Commands
  76. 71042
  77. Node: Info Formatting
  78. 74311
  79. Node: Printing
  80. 75635
  81. Node: Texinfo Mode Summary
  82. 77399
  83. Node: Beginning a File
  84. 82167
  85. Node: Four Parts
  86. 83056
  87. Node: Sample Beginning
  88. 84502
  89. Node: Header
  90. 86125
  91. Node: First Line
  92. 87476
  93. Node: Start of Header
  94. 88448
  95. Node: setfilename
  96. 89163
  97. Node: settitle
  98. 90763
  99. Node: setchapternewpage
  100. 92646
  101. Node: paragraphindent
  102. 95412
  103. Node: End of Header
  104. 96877
  105. Node: Info Summary and Permissions
  106. 97717
  107. Node: Titlepage & Copyright Page
  108. 98738
  109. Node: titlepage
  110. 100344
  111. Node: titlefont center sp
  112. 102665
  113. Node: title subtitle author
  114. 103895
  115. Node: Copyright & Permissions
  116. 106171
  117. Node: end titlepage
  118. 108176
  119. Node: headings on off
  120. 109881
  121. Node: The Top Node
  122. 111707
  123. Node: Title of Top Node
  124. 112862
  125. Node: Master Menu Parts
  126. 114099
  127. Node: Software Copying Permissions
  128. 116150
  129. Node: Ending a File
  130. 117318
  131. Node: Printing Indices & Menus
  132. 118165
  133. Node: Contents
  134. 120448
  135. Node: File End
  136. 122790
  137. Node: Structuring
  138. 123462
  139. Node: Tree Structuring
  140. 125043
  141. Node: Structuring Command Types
  142. 126467
  143. Node: makeinfo top
  144. 128792
  145. Node: chapter
  146. 129323
  147. Node: unnumbered & appendix
  148. 130147
  149. Node: majorheading & chapheading
  150. 130986
  151. Node: section
  152. 131808
  153. Node: unnumberedsec appendixsec heading
  154. 132573
  155. Node: subsection
  156. 133560
  157. Node: unnumberedsubsec appendixsubsec subheading
  158. 134131
  159. Node: subsubsection
  160. 135083
  161. Node: Nodes
  162. 136603
  163. Node: Two Paths
  164. 137538
  165. Node: Node Menu Illustration
  166. 138810
  167. Node: node
  168. 142510
  169. Node: Node Names
  170. 145206
  171. Node: Writing a Node
  172. 146271
  173. Node: Node Line Tips
  174. 148291
  175. Node: Node Line Requirements
  176. 149083
  177. Node: First Node
  178. 150691
  179. Node: makeinfo top command
  180. 151811
  181. Node: Top Node Summary
  182. 153591
  183. Node: makeinfo Pointer Creation
  184. 154728
  185. Node: Menus
  186. 155977
  187. Node: Menu Location
  188. 157220
  189. Node: Writing a Menu
  190. 158884
  191. Node: Menu Parts
  192. 159850
  193. Node: Less Cluttered Menu Entry
  194. 160848
  195. Node: Menu Example
  196. 161473
  197. Node: Other Info Files
  198. 162995
  199. Node: Cross References
  200. 164855
  201. Node: References
  202. 165734
  203. Node: Cross Reference Commands
  204. 167458
  205. Node: Cross Reference Parts
  206. 168509
  207. Node: xref
  208. 171238
  209. Node: Reference Syntax
  210. 172035
  211. Node: One Argument
  212. 173679
  213. Node: Two Arguments
  214. 174690
  215. Node: Three Arguments
  216. 175804
  217. Node: Four and Five Arguments
  218. 178189
  219. Node: Top Node Naming
  220. 180602
  221. Node: ref
  222. 181610
  223. Node: pxref
  224. 182998
  225. Node: inforef
  226. 185382
  227. Node: Marking Text
  228. 186662
  229. Node: Indicating
  230. 187283
  231. Node: Useful Highlighting
  232. 189014
  233. Node: code
  234. 190199
  235. Node: kbd
  236. 193243
  237. Node: key
  238. 194431
  239. Node: samp
  240. 195985
  241. Node: var
  242. 197497
  243. Node: file
  244. 199287
  245. Node: dfn
  246. 199893
  247. Node: cite
  248. 200802
  249. Node: Emphasis
  250. 201243
  251. Node: emph & strong
  252. 202071
  253. Node: Smallcaps
  254. 203041
  255. Node: Fonts
  256. 204371
  257. Node: Quotations and Examples
  258. 205427
  259. Node: Block Enclosing Commands
  260. 207048
  261. Node: quotation
  262. 209043
  263. Node: example
  264. 210132
  265. Node: noindent
  266. 212190
  267. Node: Lisp Example
  268. 213657
  269. Node: smallexample & smalllisp
  270. 214488
  271. Node: display
  272. 216516
  273. Node: format
  274. 217146
  275. Node: exdent
  276. 217605
  277. Node: flushleft & flushright
  278. 218684
  279. Node: cartouche
  280. 219946
  281. Node: Lists and Tables
  282. 220716
  283. Node: Introducing Lists
  284. 221311
  285. Node: itemize
  286. 222953
  287. Node: enumerate
  288. 225104
  289. Node: Two-column Tables
  290. 227594
  291. Node: table
  292. 228287
  293. Node: ftable vtable
  294. 230601
  295. Node: itemx
  296. 231644
  297. Node: Indices
  298. 232604
  299. Node: Index Entries
  300. 233753
  301. Node: Predefined Indices
  302. 234870
  303. Node: Indexing Commands
  304. 235865
  305. Node: Combining Indices
  306. 239873
  307. Node: syncodeindex
  308. 241235
  309. Node: synindex
  310. 242874
  311. Node: New Indices
  312. 243398
  313. Node: Insertions
  314. 245227
  315. Node: Braces Atsigns Periods
  316. 245985
  317. Node: Inserting An Atsign
  318. 247275
  319. Node: Inserting Braces
  320. 247533
  321. Node: Controlling Spacing
  322. 247932
  323. Node: dmn
  324. 249490
  325. Node: Dots Bullets
  326. 250719
  327. Node: dots
  328. 251525
  329. Node: bullet
  330. 251920
  331. Node: TeX and copyright
  332. 252297
  333. Node: tex
  334. 252861
  335. Node: copyright symbol
  336. 253233
  337. Node: minus
  338. 253479
  339. Node: Glyphs
  340. 254350
  341. Node: Glyphs Summary
  342. 255461
  343. Node: result
  344. 255973
  345. Node: expansion
  346. 256430
  347. Node: Print Glyph
  348. 257352
  349. Node: Error Glyph
  350. 258203
  351. Node: Equivalence
  352. 259021
  353. Node: Point Glyph
  354. 259683
  355. Node: Breaks
  356. 261206
  357. Node: Break Commands
  358. 262558
  359. Node: Line Breaks
  360. 263246
  361. Node: w
  362. 264248
  363. Node: sp
  364. 265066
  365. Node: page
  366. 265474
  367. Node: group
  368. 265851
  369. Node: need
  370. 267596
  371. Node: Definition Commands
  372. 268326
  373. Node: Def Cmd Template
  374. 269897
  375. Node: Optional Arguments
  376. 272807
  377. Node: deffnx
  378. 274396
  379. Node: Def Cmds in Detail
  380. 275352
  381. Node: Functions Commands
  382. 276462
  383. Node: Variables Commands
  384. 279391
  385. Node: Typed Functions
  386. 281340
  387. Node: Typed Variables
  388. 284875
  389. Node: Abstract Objects
  390. 286856
  391. Node: Data Types
  392. 291752
  393. Node: Def Cmd Conventions
  394. 293005
  395. Node: Sample Function Definition
  396. 293566
  397. Node: Footnotes
  398. 296490
  399. Node: Conditionals
  400. 300343
  401. Node: Conditional Commands
  402. 301099
  403. Node: Using Ordinary TeX Commands
  404. 302508
  405. Node: set clear value
  406. 303956
  407. Node: ifset ifclear
  408. 304761
  409. Node: value
  410. 307921
  411. Node: value Example
  412. 309339
  413. Node: Format/Print Hardcopy
  414. 310917
  415. Node: Use TeX
  416. 312719
  417. Node: Shell Format & Print
  418. 313310
  419. Node: Within Emacs
  420. 317908
  421. Node: Texinfo Mode Printing
  422. 318896
  423. Node: Compile-Command
  424. 322646
  425. Node: Requirements Summary
  426. 323554
  427. Node: Preparing for TeX
  428. 324974
  429. Node: Overfull hboxes
  430. 326989
  431. Node: smallbook
  432. 328549
  433. Node: A4 Paper
  434. 329782
  435. Node: Cropmarks and Magnification
  436. 330484
  437. Node: Create an Info File
  438. 332460
  439. Node: makeinfo advantages
  440. 333764
  441. Node: Invoking makeinfo
  442. 334651
  443. Node: makeinfo options
  444. 335363
  445. Node: Pointer Validation
  446. 340823
  447. Node: makeinfo in Emacs
  448. 342207
  449. Node: texinfo-format commands
  450. 344752
  451. Node: Batch Formatting
  452. 346023
  453. Node: Tag and Split Files
  454. 347269
  455. Node: Install an Info File
  456. 350626
  457. Node: Directory file
  458. 351276
  459. Node: New Info File
  460. 352956
  461. Node: Other Info Directories
  462. 354095
  463. Node: Command List
  464. 355961
  465. Node: Tips
  466. 387598
  467. Node: Sample Texinfo File
  468. 399031
  469. Node: Sample Permissions
  470. 401147
  471. Node: Inserting Permissions
  472. 402188
  473. Node: ifinfo Permissions
  474. 404469
  475. Node: Titlepage Permissions
  476. 406088
  477. Node: Include Files
  478. 407348
  479. Node: Using Include Files
  480. 408434
  481. Node: texinfo-multiple-files-update
  482. 410368
  483. Node: Include File Requirements
  484. 412759
  485. Node: Sample Include File
  486. 414004
  487. Node: Include Files Evolution
  488. 415532
  489. Node: Headings
  490. 417509
  491. Node: Headings Introduced
  492. 418144
  493. Node: Heading Format
  494. 420033
  495. Node: Heading Choice
  496. 422489
  497. Node: Custom Headings
  498. 423860
  499. Node: Catching Mistakes
  500. 428069
  501. Node: makeinfo preferred
  502. 429359
  503. Node: Debugging with Info
  504. 430260
  505. Node: Debugging with TeX
  506. 433598
  507. Node: Using texinfo-show-structure
  508. 437940
  509. Node: Using occur
  510. 441040
  511. Node: Running Info-Validate
  512. 442579
  513. Node: Using Info-validate
  514. 443639
  515. Node: Unsplit
  516. 445454
  517. Node: Tagifying
  518. 446502
  519. Node: Splitting
  520. 447361
  521. Node: Refilling Paragraphs
  522. 448981
  523. Node: Command Syntax
  524. 450800
  525. Node: Obtaining TeX
  526. 453731
  527. Node: New Features
  528. 454842
  529. Node: New Texinfo Mode Commands
  530. 455424
  531. Node: New Commands
  532. 458894
  533. Node: Command and Variable Index
  534. 463543
  535. Node: Concept Index
  536. 476101
  537. End Tag Table
  538. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  539. file texi.texi.
  540.    This file documents Texinfo, a documentation system that uses a
  541. single source file to produce both on-line information and a printed
  542. manual.
  543.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  544.    This is the second edition of the Texinfo documentation,
  545. and is consistent with version 2 of `texinfo.tex'.
  546.    Permission is granted to make and distribute verbatim copies of this
  547. manual provided the copyright notice and this permission notice are
  548. preserved on all copies.
  549.    Permission is granted to copy and distribute modified versions of
  550. this manual under the conditions for verbatim copying, provided that
  551. the entire resulting derived work is distributed under the terms of a
  552. permission notice identical to this one.
  553.    Permission is granted to copy and distribute translations of this
  554. manual into another language, under the above conditions for modified
  555. versions, except that this permission notice may be stated in a
  556. translation approved by the Free Software Foundation.
  557. File: texi.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
  558. Texinfo
  559. *******
  560.    Texinfo is a documentation system that uses a single source file to
  561. produce both on-line information and printed output.
  562.    The first part of this master menu lists the major nodes in this Info
  563. document, including the @-command and concept indices.  The rest of the
  564. menu lists all the lower level nodes in the document.
  565.    This is Edition 2.18 of the Texinfo documentation, 26 March 1993,
  566. for Texinfo Version 2.
  567. * Menu:
  568. * Copying::                     Your rights.
  569. * Overview::                    Texinfo in brief.
  570. * Texinfo Mode::                How to use Texinfo mode.
  571. * Beginning a File::            What is at the beginning of a Texinfo file?
  572. * Ending a File::               What is at the end of a Texinfo file?
  573. * Structuring::                 How to create chapters, sections, subsections,
  574.                                   appendices, and other parts.
  575. * Nodes::                       How to write nodes.
  576. * Menus::                       How to write menus.
  577. * Cross References::            How to write cross references.
  578. * Marking Text::                How to mark words and phrases as code,
  579.                                   keyboard input, meta-syntactic
  580.                                   variables, and the like.
  581. * Quotations and Examples::     How to write quotations, examples, etc.
  582. * Lists and Tables::            How to write lists and tables.
  583. * Indices::                     How to create indices.
  584. * Insertions::                  How to insert @-signs, braces, etc.
  585. * Glyphs::                      How to indicate results of evaluation,
  586.                                   expansion of macros, errors, etc.
  587. * Breaks::                      How to force and prevent line and page breaks.
  588. * Definition Commands::         How to describe functions and the like
  589.                                   in a uniform manner.
  590. * Footnotes::                   How to write footnotes.
  591. * Conditionals::                How to specify text for either TeX or Info.
  592. * Format/Print Hardcopy::       How to convert a Texinfo file to a file
  593.                                   for printing and how to print that file.
  594. * Create an Info File::         Convert a Texinfo file into an Info file.
  595. * Install an Info File::        Make an Info file accessible to users.
  596. * Command List::                All the Texinfo @-commands.
  597. * Tips::                        Hints on how to write a Texinfo document.
  598. * Sample Texinfo File::         A sample Texinfo file to look at.
  599. * Sample Permissions::          Tell readers they have the right to copy
  600.                                   and distribute.
  601. * Include Files::               How to incorporate other Texinfo files.
  602. * Headings::                    How to write page headings and footings.
  603. * Catching Mistakes::           How to find formatting mistakes.
  604. * Refilling Paragraphs::        All about paragraph refilling.
  605. * Command Syntax::              A description of @-Command syntax.
  606. * Obtaining TeX::               How to Obtain TeX.
  607. * New Features::                Texinfo second edition features.
  608. * Command and Variable Index::  A menu containing commands and variables.
  609. * Concept Index::               A menu covering many topics.
  610.  -- The Detailed Node Listing --
  611. Overview of Texinfo
  612. * Using Texinfo::               Create a conventional printed book
  613.                                   or an Info file.
  614. * Info Files::                  What is an Info file?
  615. * Printed Books::               Characteristics of a printed book or manual.
  616. * Formatting Commands::         @-commands are used for formatting.
  617. * Conventions::                 General rules for writing a Texinfo file.
  618. * Comments::                    How to write comments and mark regions that
  619.                                   the formatting commands will ignore.
  620. * Minimum::                     What a Texinfo file must have.
  621. * Six Parts::                   Usually, a Texinfo file has six parts.
  622. * Short Sample::                A short sample Texinfo file.
  623. * Acknowledgements::
  624. Using Texinfo Mode
  625. * Texinfo Mode Overview::       How Texinfo mode can help you.
  626. * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
  627.                                   purpose editing features.
  628. * Inserting::                   How to insert frequently used @-commands.
  629. * Showing the Structure::       How to show the structure of a file.
  630. * Updating Nodes and Menus::    How to update or create new nodes and menus.
  631. * Info Formatting::             How to format for Info.
  632. * Printing::                    How to format and print part or all of a file.
  633. * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
  634. Updating Nodes and Menus
  635. * Updating Commands::           Five major updating commands.
  636. * Updating Requirements::       How to structure a Texinfo file for
  637.                                   using the updating command.
  638. * Other Updating Commands::     How to indent descriptions, insert
  639.                                   missing nodes lines, and update
  640.                                   nodes in sequence.
  641. Beginning a Texinfo File
  642. * Four Parts::                  Four parts begin a Texinfo file.
  643. * Sample Beginning::            Here is a sample beginning for a Texinfo file.
  644. * Header::                      The very beginning of a Texinfo file.
  645. * Info Summary and Permissions::  Summary and copying permissions for Info.
  646. * Titlepage & Copyright Page::  Creating the title and copyright pages.
  647. * The Top Node::                Creating the `Top' node and master menu.
  648. * Software Copying Permissions::  Ensure that you and others continue to
  649.                                   have the right to use and share software.
  650. The Texinfo File Header
  651. * First Line::                  The first line of a Texinfo file.
  652. * Start of Header::             Formatting a region requires this.
  653. * setfilename::                 Tell Info the name of the Info file.
  654. * settitle::                    Create a title for the printed work.
  655. * setchapternewpage::           Start chapters on right-hand pages.
  656. * paragraphindent::             An option to specify paragraph indentation.
  657. * End of Header::               Formatting a region requires this.
  658. The Title and Copyright Pages
  659. * titlepage::                   Create a title for the printed document.
  660. * titlefont center sp::         The `@titlefont', `@center',
  661.                                   and `@sp' commands.
  662. * title subtitle author::       The `@title', `@subtitle',
  663.                                   and `@author' commands.
  664. * Copyright & Permissions::     How to write the copyright notice and
  665.                                   include copying permissions.
  666. * end titlepage::               Turn on page headings after the title and
  667.                                   copyright pages.
  668. * headings on off::             An option for turning headings on and off
  669.                                   and double or single sided printing.
  670. The `Top' Node and Master Menu
  671. * Title of Top Node::           Sketch what the file is about.
  672. * Master Menu Parts::           A master menu has three or more parts.
  673. Ending a Texinfo File
  674. * Printing Indices & Menus::    How to print an index in hardcopy and
  675.                                   generate index menus in Info.
  676. * Contents::                    How to create a table of contents.
  677. * File End::                    How to mark the end of a file.
  678. Chapter Structuring
  679. * Tree Structuring::            A manual is like an upside down tree ...
  680. * Structuring Command Types::   How to divide a manual into parts.
  681. * makeinfo top::                The `@top' command, part of the `Top' node.
  682. * chapter::
  683. * unnumbered & appendix::
  684. * majorheading & chapheading::
  685. * section::
  686. * unnumberedsec appendixsec heading::
  687. * subsection::
  688. * unnumberedsubsec appendixsubsec subheading::
  689. * subsubsection::               Commands for the lowest level sections.
  690. Nodes
  691. * Two Paths::                   Different commands to structure
  692.                                   Info output and printed output.
  693. * Node Menu Illustration::      A diagram, and sample nodes and menus.
  694. * node::                        How to write a node, in detail.
  695. * makeinfo Pointer Creation::   How to create node pointers with `makeinfo'.
  696. The `@node' Command
  697. * Node Names::                  How to choose node and pointer names.
  698. * Writing a Node::              How to write an `@node' line.
  699. * Node Line Tips::              Keep names short.
  700. * Node Line Requirements::      Keep names unique, without @-commands.
  701. * First Node::                  How to write a `Top' node.
  702. * makeinfo top command::        How to use the `@top' command.
  703. * Top Node Summary::            Write a brief description for readers.
  704. Menus
  705. * Menu Location::               Put a menu in a short node.
  706. * Writing a Menu::              What is a menu?
  707. * Menu Parts::                  A menu entry has three parts.
  708. * Less Cluttered Menu Entry::   Two part menu entry.
  709. * Menu Example::                Two and three part menu entries.
  710. * Other Info Files::            How to refer to a different Info file.
  711. Cross References
  712. * References::                  What cross references are for.
  713. * Cross Reference Commands::    A summary of the different commands.
  714. * Cross Reference Parts::       A cross reference has several parts.
  715. * xref::                        Begin a reference with `See' ...
  716. * Top Node Naming::             How to refer to the beginning of another file.
  717. * ref::                         A reference for the last part of a sentence.
  718. * pxref::                       How to write a parenthetical cross reference.
  719. * inforef::                     How to refer to an Info-only file.
  720. `@xref'
  721. * Reference Syntax::            What a reference looks like and requires.
  722. * One Argument::                `@xref' with one argument.
  723. * Two Arguments::               `@xref' with two arguments.
  724. * Three Arguments::             `@xref' with three arguments.
  725. * Four and Five Arguments::     `@xref' with four and five arguments.
  726. Marking Words and Phrases
  727. * Indicating::                  How to indicate definitions, files, etc.
  728. * Emphasis::                    How to emphasize text.
  729. Indicating Definitions, Commands, etc.
  730. * Useful Highlighting::         Highlighting provides useful information.
  731. * code::                        How to indicate code.
  732. * kbd::                         How to show keyboard input.
  733. * key::                         How to specify keys.
  734. * samp::                        How to show a literal sequence of characters.
  735. * var::                         How to indicate a metasyntactic variable.
  736. * file::                        How to indicate the name of a file.
  737. * dfn::                         How to specify a definition.
  738. * cite::                        How to refer to a book that is not in Info.
  739. Emphasizing Text
  740. * emph & strong::               How to emphasize text in Texinfo.
  741. * Smallcaps::                   How to use the small caps font.
  742. * Fonts::                       Various font commands for printed output.
  743. Quotations and Examples
  744. * Block Enclosing Commands::    Use different constructs for
  745.                                   different purposes.
  746. * quotation::                   How to write a quotation.
  747. * example::                     How to write an example in a fixed-width font.
  748. * noindent::                    How to prevent paragraph indentation.
  749. * Lisp Example::                How to illustrate Lisp code.
  750. * smallexample & smalllisp::    Forms for the `@smallbook' option.
  751. * display::                     How to write an example in the current font.
  752. * format::                      How to write an example that does not narrow
  753.                                   the margins.
  754. * exdent::                      How to undo the indentation of a line.
  755. * flushleft & flushright::      How to push text flushleft or flushright.
  756. * cartouche::                   How to draw cartouches around examples.
  757. Making Lists and Tables
  758. * Introducing Lists::           Texinfo formats lists for you.
  759. * itemize::                     How to construct a simple list.
  760. * enumerate::                   How to construct a numbered list.
  761. * Two-column Tables::           How to construct a two-column table.
  762. Making a Two-column Table
  763. * table::                       How to construct a two-column table.
  764. * ftable vtable::               How to construct a two-column table
  765.                                   with automatic indexing.
  766. * itemx::                       How to put more entries in the first column.
  767. Creating Indices
  768. * Index Entries::               Choose different words for index entries.
  769. * Predefined Indices::          Use different indices for different kinds
  770.                                   of entry.
  771. * Indexing Commands::           How to make an index entry.
  772. * Combining Indices::           How to combine indices.
  773. * New Indices::                 How to define your own indices.
  774. Combining Indices
  775. * syncodeindex::                How to merge two indices, using `@code'
  776.                                   font for the merged-from index.
  777. * synindex::                    How to merge two indices, using the
  778.                                   default font of the merged-to index.
  779. Special Insertions
  780. * Braces Atsigns Periods::      How to insert braces, `@' and periods.
  781. * dmn::                         How to format a dimension.
  782. * Dots Bullets::                How to insert dots and bullets.
  783. * TeX and copyright::           How to insert the TeX logo
  784.                                   and the copyright symbol.
  785. * minus::                       How to insert a minus sign.
  786. Inserting `@', Braces, and Periods
  787. * Inserting An Atsign::
  788. * Inserting Braces::            How to insert `{' and `}'
  789. * Controlling Spacing::         How to insert the right amount of space
  790.                                   after punctuation within a sentence.
  791. Inserting Ellipsis, Dots, and Bullets
  792. * dots::                        How to insert dots ...
  793. * bullet::                      How to insert a bullet.
  794. Inserting TeX and the Copyright Symbol
  795. * tex::                         How to insert the TeX logo.
  796. * copyright symbol::            How to use `@copyright'{}.
  797. Glyphs for Examples
  798. * Glyphs Summary::
  799. * result::                      How to show the result of expression.
  800. * expansion::                   How to indicate an expansion.
  801. * Print Glyph::                 How to indicate printed output.
  802. * Error Glyph::                 How to indicate an error message.
  803. * Equivalence::                 How to indicate equivalence.
  804. * Point Glyph::                 How to indicate the location of point.
  805. Making and Preventing Breaks
  806. * Break Commands::              Cause and prevent splits.
  807. * Line Breaks::                 How to force a single line to use two lines.
  808. * w::                           How to prevent unwanted line breaks.
  809. * sp::                          How to insert blank lines.
  810. * page::                        How to force the start of a new page.
  811. * group::                       How to prevent unwanted page breaks.
  812. * need::                        Another way to prevent unwanted page breaks.
  813. Definition Commands
  814. * Def Cmd Template::            How to structure a description using a
  815.                                   definition command.
  816. * Optional Arguments::          How to handle optional and repeated arguments.
  817. * deffnx::                      How to group two or more `first' lines.
  818. * Def Cmds in Detail::          All the definition commands.
  819. * Def Cmd Conventions::         Conventions for writing definitions.
  820. * Sample Function Definition::
  821. The Definition Commands
  822. * Functions Commands::          Commands for functions and similar entities.
  823. * Variables Commands::          Commands for variables and similar entities.
  824. * Typed Functions::             Commands for functions in typed languages.
  825. * Typed Variables::             Commands for variables in typed languages.
  826. * Abstract Objects::            Commands for object-oriented programming.
  827. * Data Types::                  The definition command for data types.
  828. Conditionally Visible Text
  829. * Conditional Commands::        How to specify text for Info or TeX.
  830. * Using Ordinary TeX Commands::  You can use any and all TeX commands.
  831. * set clear value::             How to designate which text to format (for
  832.                                   both Info and TeX); and how to set a
  833.                                   flag to a string that you can insert.
  834. `@set', `@clear', and `@value'
  835. * ifset ifclear::               Format a region if a flag is set.
  836. * value::                       Replace a flag with a string.
  837. * value Example::               An easy way to update edition information.
  838. Format and Print Hardcopy
  839. * Use TeX::                     Use TeX to format for hardcopy.
  840. * Shell Format & Print::        How to format and print a hardcopy manual
  841.                                  with shell commands.
  842. * Within Emacs::                How to format and print from an Emacs shell.
  843. * Texinfo Mode Printing::       How to format and print in Texinfo mode.
  844. * Compile-Command::             How to print using Emacs's compile command.
  845. * Requirements Summary::        TeX formatting requirements summary.
  846. * Preparing for TeX::           What you need to do to use TeX.
  847. * Overfull hboxes::             What are and what to do with overfull hboxes.
  848. * smallbook::                   How to print small format books and manuals.
  849. * A4 Paper::                    How to print on European A4 paper.
  850. * Cropmarks and Magnification::  How to print marks to indicate the size
  851.                                 of pages and how to print scaled up output.
  852. Creating an Info File
  853. * makeinfo advantages::         `makeinfo' provides better error checking.
  854. * Invoking makeinfo::           How to run `makeinfo' from a shell.
  855. * makeinfo options::            Specify fill-column and other options.
  856. * Pointer Validation::          How to check that pointers point somewhere.
  857. * makeinfo in Emacs::           How to run `makeinfo' from Emacs.
  858. * texinfo-format commands::     Two Info formatting commands written
  859.                                   in Emacs Lisp are an alternative
  860.                                   to `makeinfo'.
  861. * Batch Formatting::            How to format for Info in Emacs Batch mode.
  862. * Tag and Split Files::         How tagged and split files help Info
  863.                                   to run better.
  864. Installing an Info File
  865. * Directory file::              The top level menu for all Info files.
  866. * New Info File::               Listing a new info file.
  867. * Other Info Directories::      How to specify Info files that are
  868.                                   located in other directories.
  869. Sample Permissions
  870. * Inserting Permissions::       How to put permissions in your document.
  871. * ifinfo Permissions::          Sample `ifinfo' copying permissions.
  872. * Titlepage Permissions::       Sample Titlepage copying permissions.
  873. Include Files
  874. * Using Include Files::         How to use the `@include' command.
  875. * texinfo-multiple-files-update::  How to create and update nodes and
  876.                                   menus when using included files.
  877. * Include File Requirements::   What `texinfo-multiple-files-update' expects.
  878. * Sample Include File::         A sample outer file with included files
  879.                                   within it; and a sample included file.
  880. * Include Files Evolution::     How use of the `@include' command
  881.                                   has changed over time.
  882. Page Headings
  883. * Headings Introduced::         Conventions for using page headings.
  884. * Heading Format::              Standard page heading formats.
  885. * Heading Choice::              How to specify the type of page heading.
  886. * Custom Headings::             How to create your own headings and footings.
  887. Formatting Mistakes
  888. * makeinfo preferred::          `makeinfo' finds errors.
  889. * Debugging with Info::         How to catch errors with Info formatting.
  890. * Debugging with TeX::          How to catch errors with TeX formatting.
  891. * Using texinfo-show-structure::  How to use `texinfo-show-structure'.
  892. * Using occur::                 How to list all lines containing a pattern.
  893. * Running Info-Validate::       How to find badly referenced nodes.
  894. Finding Badly Referenced Nodes
  895. * Using Info-validate::         How to run `Info-validate'.
  896. * Unsplit::                     How to create an unsplit file.
  897. * Tagifying::                   How to tagify a file.
  898. * Splitting::                   How to split a file manually.
  899. Second Edition Features
  900. * New Texinfo Mode Commands::   The updating commands are especially useful.
  901. * New Commands::                Many newly described @-commands.
  902. File: texi.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top
  903. Texinfo Copying Conditions
  904. **************************
  905.    The programs currently being distributed that relate to Texinfo
  906. include portions of GNU Emacs, plus other separate programs (including
  907. `makeinfo', `info', `texindex', and `texinfo.tex').  These programs are
  908. "free"; this means that everyone is free to use them and free to
  909. redistribute them on a free basis.  The Texinfo-related programs are
  910. not in the public domain; they are copyrighted and there are
  911. restrictions on their distribution, but these restrictions are designed
  912. to permit everything that a good cooperating citizen would want to do.
  913. What is not allowed is to try to prevent others from further sharing
  914. any version of these programs that they might get from you.
  915.    Specifically, we want to make sure that you have the right to give
  916. away copies of the programs that relate to Texinfo, that you receive
  917. source code or else can get it if you want it, that you can change these
  918. programs or use pieces of them in new free programs, and that you know
  919. you can do these things.
  920.    To make sure that everyone has such rights, we have to forbid you to
  921. deprive anyone else of these rights.  For example, if you distribute
  922. copies of the Texinfo related programs, you must give the recipients all
  923. the rights that you have.  You must make sure that they, too, receive or
  924. can get the source code.  And you must tell them their rights.
  925.    Also, for our own protection, we must make certain that everyone
  926. finds out that there is no warranty for the programs that relate to
  927. Texinfo.  If these programs are modified by someone else and passed on,
  928. we want their recipients to know that what they have is not what we
  929. distributed, so that any problems introduced by others will not reflect
  930. on our reputation.
  931.    The precise conditions of the licenses for the programs currently
  932. being distributed that relate to Texinfo are found in the General Public
  933. Licenses that accompany them.
  934. File: texi.info,  Node: Overview,  Next: Texinfo Mode,  Prev: Copying,  Up: Top
  935. Overview of Texinfo
  936. *******************
  937.    "Texinfo"(1) is a documentation system that uses a single source
  938. file to produce both on-line information and printed output.  This
  939. means that instead of writing two different documents, one for the
  940. on-line help or other on-line information and the other for a typeset
  941. manual or other printed work, you need write only one document.  When
  942. the work is revised, you need revise only one document.  (You can read
  943. the on-line information, known as an "Info file", with an Info
  944. documentation-reading program.)
  945. * Menu:
  946. * Using Texinfo::               Create a conventional printed book
  947.                                   or an Info file.
  948. * Info Files::                  What is an Info file?
  949. * Printed Books::               Characteristics of a printed book or manual.
  950. * Formatting Commands::         @-commands are used for formatting.
  951. * Conventions::                 General rules for writing a Texinfo file.
  952. * Comments::                    How to write comments and mark regions that
  953.                                   the formatting commands will ignore.
  954. * Minimum::                     What a Texinfo file must have.
  955. * Six Parts::                   Usually, a Texinfo file has six parts.
  956. * Short Sample::                A short sample Texinfo file.
  957. * Acknowledgements::
  958.    ---------- Footnotes ----------
  959.    (1)  Note that the first syllable of "Texinfo" is pronounced like
  960. "speck", not "hex".  This odd pronunciation is derived from, but is not
  961. the same as, the pronunciation of TeX.  In the word TeX, the `X' is
  962. actually the Greek letter "chi" rather than the English letter "ex".
  963. Pronounce TeX as if the `X' were the last sound in the name `Bach'; but
  964. pronounce Texinfo as if the `x' were a `k'.  Spell "Texinfo" with a
  965. capital "T" and write the other letters in lower case.
  966. File: texi.info,  Node: Using Texinfo,  Next: Info Files,  Up: Overview
  967. Using Texinfo
  968. =============
  969.    Using Texinfo, you can create a printed document with the normal
  970. features of a book, including chapters, sections, cross references, and
  971. indices.  From the same Texinfo source file, you can create a
  972. menu-driven, on-line Info file with nodes, menus, cross references, and
  973. indices.  You can, if you wish, make the chapters and sections of the
  974. printed document correspond to the nodes of the on-line information;
  975. and you use the same cross references and indices for both the Info
  976. file and the printed work.  `The GNU Emacs Manual' is a good example of
  977. a Texinfo file, as is this manual.
  978.    To make a printed document, you process a Texinfo source file with
  979. the TeX typesetting program.  This creates a DVI file that you can
  980. typeset and print as a book or report.  (Note that the Texinfo language
  981. is completely different from TeX's usual language, PlainTeX, which
  982. Texinfo replaces.)  If you do not have TeX, but do have `troff' or
  983. `nroff', you can use the `texi2roff' program instead.
  984.    To make an Info file, you process a Texinfo source file with the
  985. `makeinfo' utility or Emacs's `texinfo-format-buffer' command; this
  986. creates an Info file that you can install on-line.
  987.    TeX and `texi2roff' work with many types of printer; similarly, Info
  988. works with almost every type of computer terminal.  This power makes
  989. Texinfo a general purpose system, but brings with it a constraint,
  990. which is that a Texinfo file may contain only the customary
  991. "typewriter" characters (letters, numbers, spaces, and punctuation
  992. marks) but no special graphics.
  993.    A Texinfo file is a plain ASCII file containing text and
  994. "@-commands" (words preceded by an `@') that tell the typesetting and
  995. formatting programs what to do.  You may edit a Texinfo file with any
  996. text editor; but it is especially convenient to use GNU Emacs since
  997. that editor has a special mode, called Texinfo mode, that provides
  998. various Texinfo-related features.  (*Note Texinfo Mode::.)
  999.    Before writing a Texinfo source file, you should become familiar with
  1000. the Info documentation reading program and learn about nodes, menus,
  1001. cross references, and the rest.  (*note info: (info)Top, for more
  1002. information.)
  1003.    You can use Texinfo to create both on-line help and printed manuals;
  1004. moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
  1005. is the format in which documentation for GNU utilities and libraries is
  1006. written.
  1007. File: texi.info,  Node: Info Files,  Next: Printed Books,  Prev: Using Texinfo,  Up: Overview
  1008. Info files
  1009. ==========
  1010.    An Info file is a Texinfo file formatted so that the Info
  1011. documentation reading program can operate on it.  (`makeinfo' and
  1012. `texinfo-format-buffer' are two commands that convert a Texinfo file
  1013. into an Info file.)
  1014.    Info files are divided into pieces called "nodes", each of which
  1015. contains the discussion of one topic.  Each node has a name, and
  1016. contains both text for the user to read and pointers to other nodes,
  1017. which are identified by their names.  The Info program displays one node
  1018. at a time, and provides commands with which the user can move to other
  1019. related nodes.
  1020.    *note info: (info)Top, for more information about using Info.
  1021.    Each node of an Info file may have any number of child nodes that
  1022. describe subtopics of the node's topic.  The names of child nodes are
  1023. listed in a "menu" within the parent node; this allows you to use
  1024. certain Info commands to move to one of the child nodes.  Generally, an
  1025. Info file is organized like a book.  If a node is at the logical level
  1026. of a chapter, its child nodes are at the level of sections; likewise,
  1027. the child nodes of sections are at the level of subsections.
  1028.    All the children of any one parent are linked together in a
  1029. bidirectional chain of `Next' and `Previous' pointers.  The `Next'
  1030. pointer provides a link to the next section, and the `Previous' pointer
  1031. provides a link to the previous section.  This means that all the nodes
  1032. that are at the level of sections within a chapter are linked together.
  1033. Normally the order in this chain is the same as the order of the
  1034. children in the parent's menu.  Each child node records the parent node
  1035. name as its `Up' pointer.  The last child has no `Next' pointer, and the
  1036. first child has the parent both as its `Previous' and as its `Up'
  1037. pointer.(1)
  1038.    The book-like structuring of an Info file into nodes that correspond
  1039. to chapters, sections, and the like is a matter of convention, not a
  1040. requirement.  The `Up', `Previous', and `Next' pointers of a node can
  1041. point to any other nodes, and a menu can contain any other nodes.
  1042. Thus, the node structure can be any directed graph.  But it is usually
  1043. more comprehensible to follow a structure that corresponds to the
  1044. structure of chapters and sections in a printed book or report.
  1045.    In addition to menus and to `Next', `Previous', and `Up' pointers,
  1046. Info provides pointers of another kind, called references, that can be
  1047. sprinkled throughout the text.  This is usually the best way to
  1048. represent links that do not fit a hierarchical structure.
  1049.    Usually, you will design a document so that its nodes match the
  1050. structure of chapters and sections in the printed output.  But there
  1051. are times when this is not right for the material being discussed.
  1052. Therefore, Texinfo uses separate commands to specify the node structure
  1053. for the Info file and the section structure for the printed output.
  1054.    Generally, you enter an Info file through a node that by convention
  1055. is called `Top'.  This node normally contains just a brief summary of
  1056. the file's purpose, and a large menu through which the rest of the file
  1057. is reached.  From this node, you can either traverse the file
  1058. systematically by going from node to node, or you can go to a specific
  1059. node listed in the main menu, or you can search the index menus and
  1060. then go directly to the node that has the information you want.
  1061.    If you want to read through an Info file in sequence, as if it were a
  1062. printed manual, you can get the whole file with the advanced Info
  1063. command `g* RET'.  (*note Advanced Info commands: (info)Expert.)
  1064.    The `dir' file in the `info' directory serves as the departure point
  1065. for the whole Info system.  From it, you can reach the `Top' nodes of
  1066. each of the documents in a complete Info system.
  1067.    ---------- Footnotes ----------
  1068.    (1)  In some documents, the first child has no `Previous' pointer.
  1069. Occasionally, the last child has the node name of the next following
  1070. higher level node as its `Next' pointer.
  1071. File: texi.info,  Node: Printed Books,  Next: Formatting Commands,  Prev: Info Files,  Up: Overview
  1072. Printed Books
  1073. =============
  1074.    A Texinfo file can be formatted and typeset as a printed book or
  1075. manual.  To do this, you need TeX, a powerful, sophisticated typesetting
  1076. program written by Donald Knuth.(1)
  1077.    A Texinfo-based book is similar to any other typeset, printed work:
  1078. it can have a title page, copyright page, table of contents, and
  1079. preface, as well as chapters, numbered or unnumbered sections and
  1080. subsections, page headers, cross references, footnotes, and indices.
  1081.    You can use Texinfo to write a book without ever having the intention
  1082. of converting it into on-line information.  You can use Texinfo for
  1083. writing a printed novel, and even to write a printed memo, although
  1084. this latter application is not recommended since electronic mail is so
  1085. much easier.
  1086.    TeX is a general purpose typesetting program.  Texinfo provides a
  1087. file called `texinfo.tex' that contains information (definitions or
  1088. "macros") that TeX uses when it typesets a Texinfo file.
  1089. (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX
  1090. commands, which TeX can then process to create the typeset document.)
  1091. `texinfo.tex' contains the specifications for printing a document.
  1092.    Most often, documents are printed on 8.5 inch by 11 inch pages
  1093. (216mm by 280mm; this is the default size), but you can also print for
  1094. 7 inch by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
  1095. European A4 size paper (`@afourpaper').  (*Note Printing "Small" Books:
  1096. smallbook.  Also, see *Note Printing on A4 Paper: A4 Paper.)
  1097.    By changing the parameters in `texinfo.tex', you can change the size
  1098. of the printed document.  In addition, you can change the style in
  1099. which the printed document is formatted; for example, you can change the
  1100. sizes and fonts used, the amount of indentation for each paragraph, the
  1101. degree to which words are hyphenated, and the like.  By changing the
  1102. specifications, you can make a book look dignified, old and serious, or
  1103. light-hearted, young and cheery.
  1104.    TeX is freely distributable.  It is written in a dialect of Pascal
  1105. called WEB and can be compiled either in Pascal or (by using a
  1106. conversion program that comes with the TeX distribution) in C.  (*Note
  1107. TeX Mode: (emacs)TeX Mode, for information about TeX.)
  1108.    TeX is very powerful and has a great many features.  Because a
  1109. Texinfo file must be able to present information both on a
  1110. character-only terminal in Info form and in a typeset book, the
  1111. formatting commands that Texinfo supports are necessarily limited.
  1112.    *Note How to Obtain TeX: Obtaining TeX.
  1113.    ---------- Footnotes ----------
  1114.    (1)  You can also use the `texi2roff' program if you do not have
  1115. TeX; since Texinfo is designed for use with TeX, `texi2roff' is not
  1116. described here.  `texi2roff' is part of the standard GNU distribution.
  1117. File: texi.info,  Node: Formatting Commands,  Next: Conventions,  Prev: Printed Books,  Up: Overview
  1118. @-commands
  1119. ==========
  1120.    In a Texinfo file, the commands that tell TeX how to typeset the
  1121. printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
  1122. create an Info file are preceded by `@'; they are called "@-commands".
  1123. For example, `@node' is the command to indicate a node and `@chapter'
  1124. is the command to indicate the start of a chapter.
  1125.      *Please note:* All the @-commands, with the exception of the
  1126.      `@TeX{}' command, must be written entirely in lower case.
  1127.    The Texinfo @-commands are a strictly limited set of constructs.  The
  1128. strict limits make it possible for Texinfo files to be understood both
  1129. by TeX and by the code that converts them into Info files.  You can
  1130. display Info files on any terminal that displays alphabetic and numeric
  1131. characters.  Similarly, you can print the output generated by TeX on a
  1132. wide variety of printers.
  1133.    Depending on what they do or what arguments(1) they take, you need
  1134. to write @-commands on lines of their own or as part of sentences:
  1135.    * Write a command such as `@noindent' at the beginning of a line as
  1136.      the only text on the line.  (`@noindent' prevents the beginning of
  1137.      the next line from being indented as the beginning of a paragraph.)
  1138.    * Write a command such as `@chapter' at the beginning of a line
  1139.      followed by the command's arguments, in this case the chapter
  1140.      title, on the rest of the line.  (`@chapter' creates chapter
  1141.      titles.)
  1142.    * Write a command such as `@dots{}' wherever you wish but usually
  1143.      within a sentence. (`@dots{}' creates dots ...)
  1144.    * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
  1145.      (but usually within a sentence) with its argument, SAMPLE-CODE in
  1146.      this example, between the braces.  (`@code' marks text as being
  1147.      code.)
  1148.    * Write a command such as `@example' at the beginning of a line of
  1149.      its own; write the body-text on following lines; and write the
  1150.      matching `@end' command, `@end example' in this case, at the
  1151.      beginning of a line of its own after the body-text. (`@example'
  1152.      ... `@end example' indents and typesets body-text as an example.)
  1153. As a general rule, a command requires braces if it mingles among other
  1154. text; but it does not need braces if it starts a line of its own.  The
  1155. non-alphabetic commands, such as `@:', are exceptions to the rule; they
  1156. do not need braces.
  1157.    As you gain experience with Texinfo, you will rapidly learn how to
  1158. write the different commands: the different ways to write commands make
  1159. it easier to write and read Texinfo files than if all commands followed
  1160. exactly the same syntax.  (For details about @-command syntax, see
  1161. *Note @-Command Syntax: Command Syntax.)
  1162.    ---------- Footnotes ----------
  1163.    (1)  The word "argument" comes from the way it is used in
  1164. mathematics and does not refer to a disputation between two people; it
  1165. refers to the information presented to the command.  According to the
  1166. `Oxford English Dictionary', the word derives from the Latin for "to
  1167. make clear, prove"; thus it came to mean `the evidence offered as
  1168. proof', which is to say, `the information offered', which led to its
  1169. mathematical meaning.  In its other thread of derivation, the word came
  1170. to mean `to assert in a manner against which others may make counter
  1171. assertions', which led to the meaning of `argument' as a disputation.
  1172. File: texi.info,  Node: Conventions,  Next: Comments,  Prev: Formatting Commands,  Up: Overview
  1173. General Syntactic Conventions
  1174. =============================
  1175.    All ASCII printing characters except `@', `{' and `}' can appear in
  1176. a Texinfo file and stand for themselves.  `@' is the escape character
  1177. which introduces commands.  `{' and `}' should be used only to surround
  1178. arguments to certain commands.  To put one of these special characters
  1179. into the document, put an `@' character in front of it, like this:
  1180. `@@', `@{', and `@}'.
  1181.    It is customary in TeX to use doubled single-quote characters to
  1182. begin and end quotations: ` ` and ' ' (but without a space between the
  1183. two single-quote characters).  This convention should be followed in
  1184. Texinfo files.  TeX converts doubled single-quote characters to left-
  1185. and right-hand doubled quotation marks and Info converts doubled
  1186. single-quote characters to ASCII double-quotes: ` ` and ' ' to " .
  1187.    Use three hyphens in a row, `---', for a dash--like this.  In TeX, a
  1188. single or even a double hyphen produces a printed dash that is shorter
  1189. than the usual typeset dash. Info reduces three hyphens to two for
  1190. display on the screen.
  1191.    To prevent a paragraph from being indented in the printed manual, put
  1192. the command `@noindent' on a line by itself before the paragraph.
  1193.    If you mark off a region of the Texinfo file with the `@iftex' and
  1194. `@end iftex' commands, that region will appear only in the printed
  1195. copy; in that region, you can use certain commands borrowed from
  1196. PlainTeX that you cannot use in Info.  Likewise, if you mark off a
  1197. region with the `@ifinfo' and `@end ifinfo' commands, that region will
  1198. appear only in the Info file; in that region, you can use Info commands
  1199. that you cannot use in TeX.  (*Note Conditionals::.)
  1200.      *Caution:* Do not use tabs in a Texinfo file!  TeX uses
  1201.      variable-width fonts, which means that it cannot predefine a tab
  1202.      to work in all circumstances.  Consequently, TeX treats tabs like
  1203.      single spaces, and that is not what they look like.
  1204.      To avoid this problem, Texinfo mode causes GNU Emacs to insert
  1205.      multiple spaces when you press the TAB key.
  1206.      Also, you can run `untabify' in Emacs to convert tabs in a region
  1207.      to multiple spaces.
  1208. File: texi.info,  Node: Comments,  Next: Minimum,  Prev: Conventions,  Up: Overview
  1209. Comments
  1210. ========
  1211.    You can write comments in a Texinfo file that will not appear in
  1212. either the Info file or the printed manual by using the `@comment'
  1213. command (which may be abbreviated to `@c').  Such comments are for the
  1214. person who reads the Texinfo file.  All the text on a line that follows
  1215. either `@comment' or `@c' is a comment; the rest of the line does not
  1216. appear in either the Info file or the printed manual. (Often, you can
  1217. write the `@comment' or `@c' in the middle of a line, and only the text
  1218. that follows after the `@comment' or `@c' command does not appear; but
  1219. some commands, such as `@settitle' and `@setfilename', work on a whole
  1220. line.  You cannot use `@comment' or `@c' in a line beginning with such
  1221. a command.)
  1222.    You can write long stretches of text that will not appear in either
  1223. the Info file or the printed manual by using the `@ignore' and `@end
  1224. ignore' commands.  Write each of these commands on a line of its own,
  1225. starting each command at the beginning of the line.  Text between these
  1226. two commands does not appear in the processed output.  You can use
  1227. `@ignore' and `@end ignore' for writing comments.  Often, `@ignore' and
  1228. `@end ignore' is used to enclose a part of the copying permissions that
  1229. applies to the Texinfo source file of a document, but not to the Info
  1230. or printed version of the document.
  1231. File: texi.info,  Node: Minimum,  Next: Six Parts,  Prev: Comments,  Up: Overview
  1232. What a Texinfo File Must Have
  1233. =============================
  1234.    By convention, the names of Texinfo files end with one of the
  1235. extensions `.texinfo', `.texi', or `.tex'.  The longer extension is
  1236. preferred since it describes more clearly to a human reader the nature
  1237. of the file.  The shorter extensions are for operating systems that
  1238. cannot handle long file names.
  1239.    In order to be made into a printed manual and an Info file, a
  1240. Texinfo file *must* begin with lines like this:
  1241.      \input texinfo
  1242.      @setfilename INFO-FILE-NAME
  1243.      @settitle NAME-OF-MANUAL
  1244. The contents of the file follow this beginning, and then you *must* end
  1245. a Texinfo file with a line like this:
  1246.      @bye
  1247. The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
  1248. which tells TeX how to translate the Texinfo @-commands into TeX
  1249. typesetting commands.  (Note the use of the backslash, `\'; this is
  1250. correct for TeX.)  The `@setfilename' line provides a name for the Info
  1251. file and the `@settitle' line specifies a title for the page headers (or
  1252. footers) of the printed manual.
  1253.    The `@bye' line at the end of the file on a line of its own tells
  1254. the formatters that the file is ended and to stop formatting.
  1255.    Usually, you will not use quite such a spare format, but will include
  1256. mode setting and start-of-header and end-of-header lines at the
  1257. beginning of a Texinfo file, like this:
  1258.      \input texinfo   @c -*-texinfo-*-
  1259.      @c %**start of header
  1260.      @setfilename INFO-FILE-NAME
  1261.      @settitle NAME-OF-MANUAL
  1262.      @c %**end of header
  1263. In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
  1264. mode when you edit the file.
  1265.    The `@c' lines which surround the `@setfilename' and `@settitle'
  1266. lines are optional, but you need them in order to run TeX or Info on
  1267. just part of the file.  (*Note Start of Header::, for more information.)
  1268.    Furthermore, you will usually provide a Texinfo file with a title
  1269. page, indices, and the like.  But the minimum, which can be useful for
  1270. short documents, is just the three lines at the beginning and the one
  1271. line at the end.
  1272. File: texi.info,  Node: Six Parts,  Next: Short Sample,  Prev: Minimum,  Up: Overview
  1273. Six Parts of a Texinfo File
  1274. ===========================
  1275.    Generally, a Texinfo file contains more than the minimal beginning
  1276. and end--it usually contains six parts:
  1277. 1. Header
  1278.      The "Header" names the file, tells TeX which definitions' file to
  1279.      use, and performs other "housekeeping" tasks.
  1280. 2. Summary Description and Copyright
  1281.      The "Summary Description and Copyright" segment describes the
  1282.      document and contains the copyright notice and copying permissions
  1283.      for the Info file.  The segment must be enclosed between `@ifinfo'
  1284.      and `@end ifinfo' commands so that the formatters place it only in
  1285.      the Info file.
  1286. 3. Title and Copyright
  1287.      The "Title and Copyright" segment contains the title and copyright
  1288.      pages and copying permissions for the printed manual.  The segment
  1289.      must be enclosed between `@titlepage' and `@end titlepage'
  1290.      commands.  The title and copyright page appear only in the printed
  1291.      manual.
  1292. 4. `Top' Node and Master Menu
  1293.      The "Master Menu" contains a complete menu of all the nodes in the
  1294.      whole Info file.  It appears only in the Info file, in the `Top'
  1295.      node.
  1296. 5. Body
  1297.      The "Body" of the document may be structured like a traditional
  1298.      book or encyclopedia or it may be free form.
  1299. 6. End
  1300.      The "End" contains commands for printing indices and generating
  1301.      the table of contents, and the `@bye' command on a line of its own.
  1302. File: texi.info,  Node: Short Sample,  Next: Acknowledgements,  Prev: Six Parts,  Up: Overview
  1303. A Short Sample Texinfo File
  1304. ===========================
  1305.    Here is a complete but very short Texinfo file, in 6 parts.  The
  1306. first three parts of the file, from `\input texinfo' through to `@end
  1307. titlepage', look more intimidating than they are.  Most of the material
  1308. is standard boilerplate; when you write a manual, simply insert the
  1309. names for your own manual in this segment. (*Note Beginning a File::.)
  1310. In the following, the sample text is *indented*; comments on it are
  1311. not.  The complete file, without any comments, is shown in *Note Sample
  1312. Texinfo File::.
  1313. Part 1: Header
  1314. --------------
  1315. The header does not appear in either the Info file or the
  1316. printed output.  It sets various parameters, including the
  1317. name of the Info file and the title used in the header.
  1318.      \input texinfo   @c -*-texinfo-*-
  1319.      @c %**start of header
  1320.      @setfilename sample.info
  1321.      @settitle Sample Document
  1322.      @c %**end of header
  1323.      
  1324.      @setchapternewpage odd
  1325. Part 2: Summary Description and Copyright
  1326. -----------------------------------------
  1327. The summary description and copyright segment does not
  1328. appear in the printed document.
  1329.      @ifinfo
  1330.      This is a short example of a complete Texinfo file.
  1331.      
  1332.      Copyright @copyright{} 1990 Free Software Foundation, Inc.
  1333.      @end ifinfo
  1334. Part 3: Titlepage and Copyright
  1335. -------------------------------
  1336. The titlepage segment does not appear in the Info file.
  1337.      @titlepage
  1338.      @sp 10
  1339.      @comment The title is printed in a large font.
  1340.      @center @titlefont{Sample Title}
  1341.      
  1342.      @c The following two commands start the copyright page.
  1343.      @page
  1344.      @vskip 0pt plus 1filll
  1345.      Copyright @copyright{} 1990 Free Software Foundation, Inc.
  1346.      @end titlepage
  1347. Part 4: `Top' Node and Master Menu
  1348. ----------------------------------
  1349. The `Top' node contains the master menu for the Info file.
  1350. Since a printed manual uses a table of contents rather than
  1351. a menu, the master menu appears only in the Info file.
  1352.      @node    Top,       First Chapter, (dir),    (dir)
  1353.      @comment node-name, next,          previous, up
  1354.      @menu
  1355.      * First Chapter::    The first chapter is the
  1356.                           only chapter in this sample.
  1357.      * Concept Index::    This index has two entries.
  1358.      @end menu
  1359. Part 5:  The Body of the Document
  1360. ---------------------------------
  1361. The body segment contains all the text of the document, but not the
  1362. indices or table of contents.  This example illustrates a node and a
  1363. chapter containing an enumerated list.
  1364.      @node    First Chapter, Concept Index, Top,      Top
  1365.      @comment node-name,     next,          previous, up
  1366.      @chapter First Chapter
  1367.      @cindex Sample index entry
  1368.      
  1369.      This is the contents of the first chapter.
  1370.      @cindex Another sample index entry
  1371.      
  1372.      Here is a numbered list.
  1373.      
  1374.      @enumerate
  1375.      @item
  1376.      This is the first item.
  1377.      
  1378.      @item
  1379.      This is the second item.
  1380.      @end enumerate
  1381.      
  1382.      The @code{makeinfo} and @code{texinfo-format-buffer}
  1383.      commands transform a Texinfo file such as this into
  1384.      an Info file; and @TeX{} typesets it for a printed
  1385.      manual.
  1386. Part 6: The End of the Document
  1387. -------------------------------
  1388. The end segment contains commands both for generating an index in a node
  1389. and unnumbered chapter of its own and for generating the table of
  1390. contents; and it contains the `@bye' command that marks the end of the
  1391. document.
  1392.      @node    Concept Index,    ,  First Chapter, Top
  1393.      @comment node-name,    next,  previous,      up
  1394.      @unnumbered Concept Index
  1395.      
  1396.      @printindex cp
  1397.      
  1398.      @contents
  1399.      @bye
  1400. The Results
  1401. -----------
  1402.    Here is what the contents of the first chapter of the sample look
  1403. like:
  1404.      This is the contents of the first chapter.
  1405.      Here is a numbered list.
  1406.        1. This is the first item.
  1407.        2. This is the second item.
  1408.      The `makeinfo' and `texinfo-format-buffer' commands transform a
  1409.      Texinfo file such as this into an Info file; and TeX typesets it
  1410.      for a printed manual.
  1411. File: texi.info,  Node: Acknowledgements,  Prev: Short Sample,  Up: Overview
  1412. Acknowledgements
  1413. ================
  1414.    Richard M. Stallman wrote Edition 1.0 of this manual.
  1415. Robert J. Chassell revised and extended it, starting with Edition 1.1.
  1416.    Our thanks go out to all who helped improve this work, particularly
  1417. to Francois Pinard and David D. Zuhn, who tirelessly recorded and
  1418. reported mistakes and obscurities; our special thanks go to
  1419. Melissa Weisshaus for her frequent and often tedious reviews of nearly
  1420. similar editions.  Our mistakes are our own.
  1421. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  1422. file texi.texi.
  1423.    This file documents Texinfo, a documentation system that uses a
  1424. single source file to produce both on-line information and a printed
  1425. manual.
  1426.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  1427.    This is the second edition of the Texinfo documentation,
  1428. and is consistent with version 2 of `texinfo.tex'.
  1429.    Permission is granted to make and distribute verbatim copies of this
  1430. manual provided the copyright notice and this permission notice are
  1431. preserved on all copies.
  1432.    Permission is granted to copy and distribute modified versions of
  1433. this manual under the conditions for verbatim copying, provided that
  1434. the entire resulting derived work is distributed under the terms of a
  1435. permission notice identical to this one.
  1436.    Permission is granted to copy and distribute translations of this
  1437. manual into another language, under the above conditions for modified
  1438. versions, except that this permission notice may be stated in a
  1439. translation approved by the Free Software Foundation.
  1440. File: texi.info,  Node: Debugging with TeX,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes
  1441. Catching Errors with TeX Formatting
  1442. ===================================
  1443.    You can also catch mistakes when you format a file with TeX.
  1444.    Usually, you do this after you have run `texinfo-format-buffer' (or,
  1445. better, `makeinfo-buffer') on the same file, because
  1446. `texinfo-format-buffer' sometimes displays error messages that make
  1447. more sense than TeX.  (*Note Debugging with Info::, for more
  1448. information.)
  1449.    For example, TeX was run on a Texinfo file, part of which is shown
  1450. here:
  1451.      ---------- Buffer: texinfo.texi ----------
  1452.      name of the texinfo file as an extension.  The
  1453.      @samp{??} are `wildcards' that cause the shell to
  1454.      substitute all the raw index files.  (@xref{sorting
  1455.      indices, for more information about sorting
  1456.      indices.)@refill
  1457.      ---------- Buffer: texinfo.texi ----------
  1458. (The cross reference lacks a closing brace.) TeX produced the following
  1459. output, after which it stopped:
  1460.      ---------- Buffer: *texinfo-tex-shell* ----------
  1461.      Runaway argument?
  1462.      {sorting indices, for more information about sorting
  1463.      indices.) @refill @ETC.
  1464.      ! Paragraph ended before @xref was complete.
  1465.      <to be read again>
  1466.                         @par
  1467.      l.27
  1468.      
  1469.      ?
  1470.      ---------- Buffer: *texinfo-tex-shell* ----------
  1471.    In this case, TeX produced an accurate and understandable error
  1472. message:
  1473.      Paragraph ended before @xref was complete.
  1474. `@par' is an internal TeX command of no relevance to Texinfo.  `l.27'
  1475. means that TeX detected the problem on line 27 of the Texinfo file.
  1476. The `?' is the prompt TeX uses in this circumstance.
  1477.    Unfortunately, TeX is not always so helpful, and sometimes you must
  1478. truly be a Sherlock Holmes to discover what went wrong.
  1479.    In any case, if you run into a problem like this, you can do one of
  1480. three things.
  1481.   1. You can tell TeX to continue running and ignore just this error by
  1482.      typing RET at the `?' prompt.
  1483.   2. You can tell TeX to continue running and to ignore all errors as
  1484.      best it can by typing `r RET' at the `?' prompt.
  1485.      This is often the best thing to do.  However, beware: the one error
  1486.      may produce a cascade of additional error messages as its
  1487.      consequences are felt through the rest of the file.  (To stop TeX
  1488.      when it is producing such an avalanche of error messages, type
  1489.      `C-d' (or `C-c C-d', if you are running a shell inside Emacs
  1490.      Version 18.))
  1491.   3. You can tell TeX to stop this run by typing `x RET' at the `?'
  1492.      prompt.
  1493.    Please note that if you are running TeX inside Emacs, you need to
  1494. switch to the shell buffer and line at which TeX offers the `?' prompt.
  1495.    Sometimes TeX will format a file without producing error messages
  1496. even though there is a problem.  This usually occurs if a command is
  1497. not ended but TeX is able to continue processing anyhow.  For example,
  1498. if you fail to end an itemized list with the `@end itemize' command,
  1499. TeX will write a DVI file that you can print out.  The only error
  1500. message that TeX will give you is the somewhat mysterious comment that
  1501.      (@end occurred inside a group at level 1)
  1502. However, if you print the DVI file, you will find that the text of the
  1503. file that follows the itemized list is entirely indented as if it were
  1504. part of the last item in the itemized list.  The error message is the
  1505. way TeX says that it expected to find an `@end' command somewhere in
  1506. the file; but that it could not determine where it was needed.
  1507.    Another source of notoriously hard-to-find errors is a missing `@end
  1508. group' command.  If you ever are stumped by incomprehensible errors,
  1509. look for a missing `@end group' command first.
  1510.    If the Texinfo file lacks header lines, TeX may stop in the
  1511. beginning of its run and display output that looks like the following.
  1512. The `*' indicates that TeX is waiting for input.
  1513.      This is TeX, Version 2.0 for Berkeley UNIX
  1514.      (preloaded format=plain-cm 87.10.25)
  1515.      (test.texinfo [1])
  1516.      *
  1517. In this case, simply type `\end RET' after the asterisk.  Then write
  1518. the header lines in the Texinfo file and run the TeX command again.
  1519. (Note the use of the backslash, `\'.  TeX uses `\' instead of `@'; and
  1520. in this circumstance, you are working directly with TeX, not with
  1521. Texinfo.)
  1522. File: texi.info,  Node: Using texinfo-show-structure,  Next: Using occur,  Prev: Debugging with TeX,  Up: Catching Mistakes
  1523. Using `texinfo-show-structure'
  1524. ==============================
  1525.    It is not always easy to keep track of the nodes, chapters,
  1526. sections, and subsections of a Texinfo file.  This is especially true
  1527. if you are revising or adding to a Texinfo file that someone else has
  1528. written.
  1529.    In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
  1530. lists all the lines that begin with the @-commands that specify the
  1531. structure: `@chapter', `@section', `@appendix', and so on.  With an
  1532. argument (`C-u' as prefix argument, if interactive), the command also
  1533. shows the `@node' lines.  The `texinfo-show-structure' command is bound
  1534. to `C-c C-s' in Texinfo mode, by default.
  1535.    The lines are displayed in a buffer called the `*Occur*' buffer.
  1536. For example, when `texinfo-show-structure' was run on an earlier
  1537. version of this appendix, it produced the following:
  1538.      Lines matching "^@\\(chapter \\|sect\\|sub\\|unnum\\|major\\|
  1539.      heading \\|appendix\\)" in buffer texinfo.texi.
  1540.        4:@appendix Formatting Mistakes
  1541.       52:@appendixsec Catching Errors with Info Formatting
  1542.      222:@appendixsec Catching Errors with @TeX{} Formatting
  1543.      338:@appendixsec Using @code{texinfo-show-structure}
  1544.      407:@appendixsubsec Using @code{occur}
  1545.      444:@appendixsec Finding Badly Referenced Nodes
  1546.      513:@appendixsubsec Running @code{Info-validate}
  1547.      573:@appendixsubsec Splitting a File Manually
  1548.    This says that lines 4, 52, and 222 of `texinfo.texi' begin with the
  1549. `@appendix', `@appendixsec', and `@appendixsec' commands respectively.
  1550. If you move your cursor into the `*Occur*' window, you can position the
  1551. cursor over one of the lines and use the `C-c C-c' command
  1552. (`occur-mode-goto-occurrence'), to jump to the corresponding spot in
  1553. the Texinfo file.  *Note Using Occur: (emacs)Other Repeating Search,
  1554. for more information about `occur-mode-goto-occurrence'.
  1555.    The first line in the `*Occur*' window describes the "regular
  1556. expression" specified by TEXINFO-HEADING-PATTERN.  This regular
  1557. expression is the pattern that `texinfo-show-structure' looks for.
  1558. *Note Using Regular Expressions: (emacs)Regexps, for more information.
  1559.    When you invoke the `texinfo-show-structure' command, Emacs will
  1560. display the structure of the whole buffer.  If you want to see the
  1561. structure of just a part of the buffer, of one chapter, for example,
  1562. use the `C-x n' (`narrow-to-region') command to mark the region.
  1563. (*Note Narrowing: (emacs)Narrowing.)  This is how the example used
  1564. above was generated.  (To see the whole buffer again, use `C-x w'
  1565. (`widen').)
  1566.    If you call `texinfo-show-structure' with a prefix argument by
  1567. typing `C-u C-c C-s', it will list lines beginning with `@node' as well
  1568. as the lines beginning with the @-sign commands for `@chapter',
  1569. `@section', and the like.
  1570.    You can remind yourself of the structure of a Texinfo file by
  1571. looking at the list in the `*Occur*' window; and if you have mis-named
  1572. a node or left out a section, you can correct the mistake.
  1573. File: texi.info,  Node: Using occur,  Next: Running Info-Validate,  Prev: Using texinfo-show-structure,  Up: Catching Mistakes
  1574. Using `occur'
  1575. =============
  1576.    Sometimes the `texinfo-show-structure' command produces too much
  1577. information.  Perhaps you want to remind yourself of the overall
  1578. structure of a Texinfo file, and are overwhelmed by the detailed list
  1579. produced by `texinfo-show-structure'.  In this case, you can use the
  1580. `occur' command directly.  To do this, type
  1581.      `M-x occur'
  1582. and then, when prompted, type a "regexp", a regular expression for the
  1583. pattern you want to match.  (*Note Regular Expressions:
  1584. (emacs)Regexps.)  The `occur' command works from the current location
  1585. of the cursor in the buffer to the end of the buffer.  If you want to
  1586. run `occur' on the whole buffer, place the cursor at the beginning of
  1587. the buffer.
  1588.    For example, to see all the lines that contain the word `@chapter'
  1589. in them, just type `@chapter'.  This will produce a list of the
  1590. chapters.  It will also list all the sentences with `@chapter' in the
  1591. middle of the line.
  1592.    If you want to see only those lines that start with the word
  1593. `@chapter', type `^@chapter' when prompted by `occur'.  If you want to
  1594. see all the lines that end with a word or phrase, end the last word
  1595. with a `$'; for example, `catching mistakes$'.  This can be helpful
  1596. when you want to see all the nodes that are part of the same chapter or
  1597. section and therefore have the same `Up' pointer.
  1598.    *Note Using Occur: (emacs)Other Repeating Search, for more
  1599. information.
  1600. File: texi.info,  Node: Running Info-Validate,  Prev: Using occur,  Up: Catching Mistakes
  1601. Finding Badly Referenced Nodes
  1602. ==============================
  1603.    You can use the `Info-validate' command to check whether any of the
  1604. `Next', `Previous', `Up' or other node pointers fail to point to a
  1605. node.  This command checks that every node pointer points to an
  1606. existing node.  The `Info-validate' command works only on Info files,
  1607. not on Texinfo files.
  1608.    The `makeinfo' program validates pointers automatically, so you do
  1609. not need to use the `Info-validate' command if you are using
  1610. `makeinfo'.  You only may need to use `Info-validate' if you are unable
  1611. to run `makeinfo' and instead must create an Info file using
  1612. `texinfo-format-region' or `texinfo-format-buffer', or if you write an
  1613. Info file from scratch.
  1614. * Menu:
  1615. * Using Info-validate::         How to run `Info-validate'.
  1616. * Unsplit::                     How to create an unsplit file.
  1617. * Tagifying::                   How to tagify a file.
  1618. * Splitting::                   How to split a file manually.
  1619. File: texi.info,  Node: Using Info-validate,  Next: Unsplit,  Up: Running Info-Validate
  1620. Running `Info-validate'
  1621. -----------------------
  1622.    To use `Info-validate', visit the Info file you wish to check and
  1623. type:
  1624.      M-x Info-validate
  1625. (Note that the `Info-validate' command requires an upper case `I'.  You
  1626. may also need to create a tag table before running `Info-validate'.
  1627. *Note Tagifying::.)
  1628.    If your file is valid, you will receive a message that says "File
  1629. appears valid".  However, if you have a pointer that does not point to
  1630. a node, error messages will be displayed in a buffer called `*problems
  1631. in info file*'.
  1632.    For example, `Info-validate' was run on a test file that contained
  1633. only the first node of this manual.  One of the messages said:
  1634.      In node "Overview", invalid Next: Texinfo Mode
  1635. This meant that the node called `Overview' had a `Next' pointer that
  1636. did not point to anything (which was true in this case, since the test
  1637. file had only one node in it).
  1638.    Now suppose we add a node named `Texinfo Mode' to our test case but
  1639. we do not specify a `Previous' for this node.  Then we will get the
  1640. following error message:
  1641.      In node "Texinfo Mode", should have Previous: Overview
  1642. This is because every `Next' pointer should be matched by a `Previous'
  1643. (in the node where the `Next' points) which points back.
  1644.    `Info-validate' also checks that all menu entries and cross
  1645. references point to actual nodes.
  1646.    Note that `Info-validate' requires a tag table and does not work
  1647. with files that have been split.  (The `texinfo-format-buffer' command
  1648. automatically splits large files.)  In order to use `Info-validate' on
  1649. a large file, you must run `texinfo-format-buffer' with an argument so
  1650. that it does not split the Info file; and you must create a tag table
  1651. for the unsplit file.
  1652. File: texi.info,  Node: Unsplit,  Next: Tagifying,  Prev: Using Info-validate,  Up: Running Info-Validate
  1653. Creating an Unsplit File
  1654. ------------------------
  1655.    You can run `Info-validate' only on a single Info file that has a
  1656. tag table.  The command will not work on the indirect subfiles that are
  1657. generated when a master file is split.  If you have a large file
  1658. (longer than 70,000 bytes or so), you need to run the
  1659. `texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
  1660. it does not create indirect subfiles.  You will also need to create a
  1661. tag table for the Info file.  After you have done this, you can run
  1662. `Info-validate' and look for badly referenced nodes.
  1663.    The first step is to create an unsplit Info file.
  1664.    To prevent `texinfo-format-buffer' from splitting a Texinfo file
  1665. into smaller Info files, give a prefix to the `M-x
  1666. texinfo-format-buffer' command:
  1667.      C-u M-x texinfo-format-buffer
  1668. or else
  1669.      C-u C-c C-e C-b
  1670. When you do this, Texinfo will not split the file and will not create a
  1671. tag table for it.
  1672. File: texi.info,  Node: Tagifying,  Next: Splitting,  Prev: Unsplit,  Up: Running Info-Validate
  1673. Tagifying a File
  1674. ----------------
  1675.    After creating an unsplit Info file, you must create a tag table for
  1676. it.  Visit the Info file you wish to tagify and type:
  1677.      M-x Info-tagify
  1678. (Note the upper case I in `Info-tagify'.)  This creates an Info file
  1679. with a tag table that you can validate.
  1680.    The third step is to validate the Info file:
  1681.      M-x Info-validate
  1682. (Note the upper case I in `Info-validate'.) In brief, the steps are:
  1683.      C-u M-x texinfo-format-buffer
  1684.      M-x Info-tagify
  1685.      M-x Info-validate
  1686.    After you have validated the node structure, you will be able to
  1687. rerun `texinfo-format-buffer' in the normal way so it will construct a
  1688. tag table and split the file automatically, or you can make the tag
  1689. table and split the file manually.
  1690. File: texi.info,  Node: Splitting,  Prev: Tagifying,  Up: Running Info-Validate
  1691. Splitting a File Manually
  1692. -------------------------
  1693.    You should split a large file or else let the
  1694. `texinfo-format-buffer' or `makeinfo-buffer' command do it for you
  1695. automatically.  (Generally you will let one of the formatting commands
  1696. do this job for you.  *Note Create an Info File::.)
  1697.    The split-off files are called the indirect subfiles.
  1698.    Info files are split to save memory.  With smaller files, Emacs does
  1699. not have make such a large buffer to hold the information.
  1700.    If an Info file has more than 30 nodes, you should also make a tag
  1701. table for it. *Note Using Info-validate::, for information about
  1702. creating a tag table.  (Again, tag tables are usually created
  1703. automatically by the formatting command; you only need to create a tag
  1704. table yourself if you are doing the job manually.  Most likely, you
  1705. will do this for a large, unsplit file on which you have run
  1706. `Info-validate'.)
  1707.    Visit the Info file you wish to tagify and split and type the two
  1708. commands:
  1709.      M-x Info-tagify
  1710.      M-x Info-split
  1711. (Note that the `I' in `Info' is upper case.)
  1712.    When you use the `Info-split' command, the buffer is modified into a
  1713. (small) Info file which lists the indirect subfiles.  This file should
  1714. be saved in place of the original visited file.  The indirect subfiles
  1715. are written in the same directory the original file is in, with names
  1716. generated by appending `-' and a number to the original file name.
  1717.    The primary file still functions as an Info file, but it contains
  1718. just the tag table and a directory of subfiles.
  1719. File: texi.info,  Node: Refilling Paragraphs,  Next: Command Syntax,  Prev: Catching Mistakes,  Up: Top
  1720. Refilling Paragraphs
  1721. ********************
  1722.    The `@refill' command refills and, optionally, indents the first
  1723. line of a paragraph.(1) The `@refill' command is no longer important,
  1724. but we describe it here because you once needed it.  You will see it in
  1725. many old Texinfo files.
  1726.    Without refilling, paragraphs containing long @-constructs may look
  1727. bad after formatting because the formatter removes @-commands and
  1728. shortens some lines more than others.  In the past, neither
  1729. `texinfo-format-region' nor `texinfo-format-buffer' refilled paragraphs
  1730. automatically.  The `@refill' command had to be written at the end of
  1731. every paragraph to cause these formatters to fill them.  (Both TeX and
  1732. `makeinfo' have always refilled paragraphs automatically.)  Now, all
  1733. the Info formatters automatically fill and indent those paragraphs that
  1734. need to be filled and indented.
  1735.    The `@refill' command causes both the `texinfo-format-region'
  1736. command and the `texinfo-format-buffer' command to refill a paragraph
  1737. in the Info file *after* all the other processing has been done.  For
  1738. this reason, you can not use `@refill' with a paragraph containing
  1739. either `@*' or `@w{ ... }' since the refilling action will override
  1740. those two commands.
  1741.    The `texinfo-format-region' and `texinfo-format-buffer' commands now
  1742. automatically append `@refill' to the end of each paragraph that should
  1743. be filled.  They do not append `@refill' to the ends of paragraphs that
  1744. contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
  1745.    ---------- Footnotes ----------
  1746.    (1)  Perhaps the command should have been called the
  1747. `@refillandindent' command, but `@refill' is shorter and the name was
  1748. chosen before indenting was possible.
  1749. File: texi.info,  Node: Command Syntax,  Next: Obtaining TeX,  Prev: Refilling Paragraphs,  Up: Top
  1750. @-Command Syntax
  1751. ****************
  1752.    The character `@' is used to start special Texinfo commands.  (It
  1753. has the same meaning that `\' has in PlainTeX.)  Texinfo has four types
  1754. of @-command:
  1755. 1. Non-alphabetic commands.
  1756.      These commands consist of an @ followed by a punctuation mark or
  1757.      other character that is not part of the alphabet.  Non-alphabetic
  1758.      commands are almost always part of the text within a paragraph,
  1759.      and never take any argument.  The two characters (@ and the other
  1760.      one) are complete in themselves; none is followed by braces.  The
  1761.      non-alphabetic commands are: `@.', `@:', `@*', `@@', `@{', and
  1762.      `@}'.
  1763. 2. Alphabetic commands that do not require arguments.
  1764.      These commands start with @ followed by a word followed by left-
  1765.      and right-hand braces.  These commands insert special symbols in
  1766.      the document; they do not require arguments.  For example,
  1767.      `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
  1768.      `@bullet{}' => `*'.
  1769. 3. Alphabetic commands that require arguments within braces.
  1770.      These commands start with @ followed by a letter or a word,
  1771.      followed by an argument within braces.  For example, the command
  1772.      `@dfn' indicates the introductory or defining use of a term; it is
  1773.      used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
  1774.      commands.'
  1775. 4. Alphabetic commands that occupy an entire line.
  1776.      These commands occupy an entire line.  The line starts with @,
  1777.      followed by the name of the command (a word); for example,
  1778.      `@center' or `@cindex'.  If no argument is needed, the word is
  1779.      followed by the end of the line.  If there is an argument, it is
  1780.      separated from the command name by a space.  Braces are not used.
  1781.    Thus, the alphabetic commands fall into classes that have different
  1782. argument syntaxes.  You cannot tell to which class a command belongs by
  1783. the appearance of its name, but you can tell by the command's meaning:
  1784. if the command stands for a glyph, it is in class 2 and does not
  1785. require an argument; if it makes sense to use the command together with
  1786. other text as part of a paragraph, the command is in class 3 and must
  1787. be followed by an argument in braces; otherwise, it is in class 4 and
  1788. uses the rest of the line as its argument.
  1789.    The purpose of having a different syntax for commands of classes 3
  1790. and 4 is to make Texinfo files easier to read, and also to help the GNU
  1791. Emacs paragraph and filling commands work properly.  There is only one
  1792. exception to this rule: the command `@refill', which is always used at
  1793. the end of a paragraph immediately following the final period or other
  1794. punctuation character.  `@refill' takes no argument and does *not*
  1795. require braces.  `@refill' never confuses the Emacs paragraph commands
  1796. because it cannot appear at the beginning of a line.
  1797. File: texi.info,  Node: Obtaining TeX,  Next: New Features,  Prev: Command Syntax,  Up: Top
  1798. How to Obtain TeX
  1799. *****************
  1800.    TeX is freely redistributable.  You can obtain TeX for Unix systems
  1801. from the University of Washington for a distribution fee.
  1802.    To order a full distribution, send $200.00 for a 1/2-inch 9-track
  1803. 1600 bpi (`tar' or `cpio') tape reel, or $210.00 for a 1/4-inch 4-track
  1804. QIC-24 (`tar' or `cpio') cartridge, to:
  1805.      Northwest Computing Support Center
  1806.      DR-10, Thomson Hall 35
  1807.      University of Washington
  1808.      Seattle, Washington 98195
  1809. Please make checks payable to the University of Washington.
  1810.    Prepaid orders are preferred but purchase orders are acceptable;
  1811. however, purchase orders carry an extra charge of $10.00, to pay for
  1812. processing.
  1813.    Overseas sites: please add to the base cost $20.00 for shipment via
  1814. air parcel post, or $30.00 for shipment via courier.
  1815.    Please check with the Northwest Computing Support Center at the
  1816. University of Washington for current prices and formats:
  1817.      telephone:  (206) 543-6259
  1818.      email:      elisabet@u.washington.edu
  1819. File: texi.info,  Node: New Features,  Next: Command and Variable Index,  Prev: Obtaining TeX,  Up: Top
  1820. Second Edition Features
  1821. ***********************
  1822.    The second edition of the Texinfo manual describes more than 20 new
  1823. Texinfo mode commands and more than 50 previously undocumented Texinfo
  1824. @-commands.  This edition is more than twice the length of the first
  1825. edition.
  1826.    Here is a brief description of the new commands.
  1827. * Menu:
  1828. * New Texinfo Mode Commands::   The updating commands are especially useful.
  1829. * New Commands::                Many newly described @-commands.
  1830. File: texi.info,  Node: New Texinfo Mode Commands,  Next: New Commands,  Up: New Features
  1831. New Texinfo Mode Commands
  1832. =========================
  1833.    Texinfo mode provides commands and features especially designed for
  1834. working with Texinfo files.  More than 20 new commands have been added,
  1835. including commands for automatically creating and updating both nodes
  1836. and menus.  This is a tedious task when done by hand.
  1837.    The keybindings are intended to be somewhat mnemonic.
  1838. Update all nodes and menus
  1839. --------------------------
  1840.    The `texinfo-master-menu' command is the primary command:
  1841. `C-c C-u m'
  1842. `M-x texinfo-master-menu'
  1843.      Create or update a master menu.  With `C-u' as a prefix argument,
  1844.      first create or update all nodes and regular menus.
  1845. Update Pointers
  1846. ---------------
  1847. Create or update `Next', `Previous', and `Up' node pointers.
  1848. *Note Updating Nodes and Menus::.
  1849. `C-c C-u C-n'
  1850. `M-x texinfo-update-node'
  1851.      Update a node.
  1852. `C-c C-u C-e'
  1853. `M-x texinfo-every-node-update'
  1854.      Update every node in the buffer.
  1855. Update Menus
  1856. ------------
  1857. Create or update menus.
  1858. *Note Updating Nodes and Menus::.
  1859. `C-c C-u C-m'
  1860. `M-x texinfo-make-menu'
  1861.      Make or update a menu.
  1862. `C-c C-u C-a'
  1863. `M-x texinfo-all-menus-update'
  1864.      Make or update all the menus in a buffer.  With `C-u' as a prefix
  1865.      argument, first update all the nodes.
  1866. Insert Title as Description
  1867. ---------------------------
  1868. Insert a node's chapter or section title in the space for the
  1869. description in a menu entry line; position point so you can edit the
  1870. insert.  (This command works somewhat differently than the other
  1871. insertion commands, which insert only a predefined string.)
  1872. *Note Inserting Frequently Used Commands: Inserting.
  1873. `C-c C-c C-d'
  1874.      Insert title.
  1875. Format for Info
  1876. ---------------
  1877. Provide keybindings both for the Info formatting commands that are
  1878. written in Emacs Lisp and for `makeinfo' that is written in C.
  1879. *Note Info Formatting::.
  1880. Use the Emacs lisp `texinfo-format...' commands:
  1881. `C-c C-e C-r'
  1882.      Format the region.
  1883. `C-c C-e C-b'
  1884.      Format the buffer.
  1885. Use `makeinfo':
  1886. `C-c C-m C-r'
  1887.      Format the region.
  1888. `C-c C-m C-b'
  1889.      Format the buffer.
  1890. `C-c C-m C-l'
  1891.      Recenter the `makeinfo' output buffer.
  1892. `C-c C-m C-k'
  1893.      Kill the `makeinfo' formatting job.
  1894. Typeset and Print
  1895. -----------------
  1896. Typeset and print Texinfo documents from within Emacs.
  1897. *Note Printing::.
  1898. `C-c C-t C-r'
  1899.      Run TeX on the region.
  1900. `C-c C-t C-b'
  1901.      Run TeX on the buffer.
  1902. `C-c C-t C-i'
  1903.      Run `texindex'.
  1904. `C-c C-t C-p'
  1905.      Print the DVI file.
  1906. `C-c C-t C-q'
  1907.      Show the print queue.
  1908. `C-c C-t C-d'
  1909.      Delete a job from the print queue.
  1910. `C-c C-t C-k'
  1911.      Kill the current TeX formatting job.
  1912. `C-c C-t C-x'
  1913.      Quit a currently stopped TeX formatting job.
  1914. `C-c C-t C-l'
  1915.      Recenter the output buffer.
  1916. Other Updating Commands
  1917. -----------------------
  1918. The "other updating commands" do not have standard keybindings because
  1919. they are used less frequently.
  1920. *Note Other Updating Commands::.
  1921. `M-x texinfo-insert-node-lines'
  1922.      Insert missing `@node' lines using section titles as node names.
  1923. `M-x texinfo-multiple-files-update'
  1924.      Update a multi-file document.  With a numeric prefix, such as `C-u
  1925.      8', update  *every* pointer and menu in *all* the files and then
  1926.      insert a master menu.
  1927. `M-x texinfo-indent-menu-description'
  1928.      Indent descriptions in menus.
  1929. `M-x texinfo-sequential-node-update'
  1930.      Insert node pointers in strict sequence.
  1931. File: texi.info,  Node: New Commands,  Prev: New Texinfo Mode Commands,  Up: New Features
  1932. New Texinfo @-Commands
  1933. ======================
  1934.    The second edition of the Texinfo manual describes more than 50
  1935. commands that were not described in the first edition.  A third or so
  1936. of these commands existed in Texinfo but were not documented in the
  1937. manual; the others are new.  Here is a listing, with brief descriptions
  1938. of them:
  1939. Indexing
  1940. --------
  1941. Create your own index, and merge indices.
  1942. *Note Indices::.
  1943. `@defindex INDEX-NAME'
  1944.      Define a new index and its indexing command.  See also the
  1945.      `@defcodeindex' command.
  1946. `@synindex FROM-INDEX INTO-INDEX'
  1947.      Merge the FROM-INDEX index into the INTO-INDEX index.  See also
  1948.      the `@syncodeindex' command.
  1949. Definitions
  1950. -----------
  1951. Describe functions, variables, macros, commands, user options, special
  1952. forms, and other such artifacts in a uniform format.
  1953. *Note Definition Commands::.
  1954. `@deffn CATEGORY NAME ARGUMENTS...'
  1955.      Format a description for functions, interactive commands, and
  1956.      similar entities.
  1957. `@defvr, @defop, ...'
  1958.      15 other related commands.
  1959. Glyphs
  1960. ------
  1961. Indicate the results of evaluation, expansion, printed output, an error
  1962. message, equivalence of expressions, and the location of point.
  1963. *Note Glyphs::.
  1964. `@equiv{}'
  1965.      Equivalence:
  1966. `@error{}'
  1967. `error-->'
  1968.      Error message
  1969. `@expansion{}'
  1970. `==>'
  1971.      Macro expansion
  1972. `@point{}'
  1973. `-!-'
  1974.      Position of point
  1975. `@print{}'
  1976.      Printed output
  1977. `@result{}'
  1978.      Result of an expression
  1979. Page Headings
  1980. -------------
  1981. Customize page headings.
  1982. *Note Headings::.
  1983. `@headings ON-OFF-SINGLE-DOUBLE'
  1984.      Headings on or off, single, or double-sided.
  1985. `@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
  1986.      Footings for even-numbered (left-hand) pages.
  1987. `@evenheading, @everyheading, @oddheading, ...'
  1988.      Five other related commands.
  1989. `@thischapter'
  1990.      Insert name of chapter and chapter number.
  1991. `@thischaptername, @thisfile, @thistitle, @thispage'
  1992.      Related commands.
  1993. Formatting
  1994. ----------
  1995. Format blocks of text.
  1996. *Note Quotations and Examples::, and
  1997. *Note Making Lists and Tables: Lists and Tables.
  1998. `@cartouche'
  1999.      Draw rounded box surrounding text (not in Info).
  2000. `@enumerate OPTIONAL-ARG'
  2001.      Enumerate a list with letters or numbers.
  2002. `@exdent LINE-OF-TEXT'
  2003.      Remove indentation.
  2004. `@flushleft'
  2005.      Left justify.
  2006. `@flushright'
  2007.      Right justify.
  2008. `@format'
  2009.      Do not narrow nor change font.
  2010. `@ftable FORMATTING-COMMAND'
  2011. `@vtable FORMATTING-COMMAND'
  2012.      Two-column table with indexing.
  2013. `@lisp'
  2014.      For an example of Lisp code.
  2015. `@smallexample'
  2016. `@smalllisp'
  2017.      Like @table and @lisp but for @smallbook.
  2018. Conditionals
  2019. ------------
  2020. Conditionally format text.
  2021. *Note `@set' `@clear' `@value': set clear value.
  2022. `@set FLAG [STRING]'
  2023.      Set a flag.  Optionally, set value of FLAG to STRING.
  2024. `@clear FLAG'
  2025.      Clear a flag.
  2026. `@value{FLAG}'
  2027.      Replace with value to which FLAG is set.
  2028. `@ifset FLAG'
  2029.      Format, if FLAG is set.
  2030. `@ifclear FLAG'
  2031.      Ignore, if FLAG is set.
  2032. @heading series for Titles
  2033. --------------------------
  2034. Produce unnumbered headings that do not appear in a table of contents.
  2035. *Note Structuring::.
  2036. `@heading TITLE'
  2037.      Unnumbered section-like heading not listed in the table of
  2038.      contents of a printed manual.
  2039. `@chapheading, @majorheading, @subheading, @subsubheading'
  2040.      Related commands.
  2041. Font commands
  2042. -------------
  2043. *Note Smallcaps::, and
  2044. *Note Fonts::.
  2045. `@r{TEXT}'
  2046.      Print in roman font.
  2047. `@sc{TEXT}'
  2048.      Print in SMALL CAPS font.
  2049. Miscellaneous
  2050. -------------
  2051. See *Note `@title' `@subtitle' and `@author' Commands: title subtitle
  2052. author,
  2053. see *Note Overfull hboxes::,
  2054. see *Note Footnotes::,
  2055. see *Note Format a Dimension: dmn,
  2056. see *Note Inserting a Minus Sign: minus,
  2057. see *Note Paragraph Indenting: paragraphindent,
  2058. see *Note Cross Reference Commands::,
  2059. see *Note `@title' `@subtitle' and `@author': title subtitle author, and
  2060. see *Note How to Make Your Own Headings: Custom Headings.
  2061. `@author AUTHOR'
  2062.      Typeset author's name.
  2063. `@finalout'
  2064.      Produce cleaner printed output.
  2065. `@footnotestyle'
  2066.      Specify footnote style.
  2067. `@dmn{DIMENSION}'
  2068.      Format a dimension.
  2069. `@minus{}'
  2070.      Generate a minus sign.
  2071. `@paragraphindent'
  2072.      Specify paragraph indentation.
  2073. `@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  2074.      Make a reference.  In the printed manual, the reference does not
  2075.      start with the word `see'.
  2076. `@title TITLE'
  2077.      Typeset TITLE in the alternative title page format.
  2078. `@subtitle SUBTITLE'
  2079.      Typeset SUBTITLE in the alternative title page format.
  2080. `@today{}'
  2081.      Insert the current date.
  2082. File: texi.info,  Node: Command and Variable Index,  Next: Concept Index,  Prev: New Features,  Up: Top
  2083. Command and Variable Index
  2084. **************************
  2085.    This is an alphabetical list of all the @-commands and several
  2086. variables.  To make the list easier to use, the commands are listed
  2087. without their preceding `@'.
  2088. * Menu:
  2089. * * (force line break):                 Line Breaks.
  2090. * .  (true end of sentence):            Controlling Spacing.
  2091. * : (suppress widening):                Controlling Spacing.
  2092. * @ (single @):                         Inserting An Atsign.
  2093. * { (single {):                         Inserting Braces.
  2094. * } (single }):                         Inserting Braces.
  2095. * afourpaper:                           A4 Paper.
  2096. * appendix:                             unnumbered & appendix.
  2097. * appendixsec:                          unnumberedsec appendixsec heading.
  2098. * appendixsection:                      unnumberedsec appendixsec heading.
  2099. * appendixsubsec:                       unnumberedsubsec appendixsubsec subheading.
  2100. * appendixsubsubsec:                    subsubsection.
  2101. * apply:                                Sample Function Definition.
  2102. * author:                               title subtitle author.
  2103. * b (bold font):                        Fonts.
  2104. * buffer-end:                           Def Cmd Template.
  2105. * bullet:                               bullet.
  2106. * bye:                                  Ending a File.
  2107. * bye:                                  File End.
  2108. * c (comment):                          Comments.
  2109. * cartouche:                            cartouche.
  2110. * center:                               titlefont center sp.
  2111. * chapheading:                          majorheading & chapheading.
  2112. * chapter:                              chapter.
  2113. * cindex:                               Indexing Commands.
  2114. * cite:                                 cite.
  2115. * clear:                                ifset ifclear.
  2116. * code:                                 code.
  2117. * comment:                              Comments.
  2118. * contents:                             Contents.
  2119. * copyright:                            copyright symbol.
  2120. * copyright:                            Copyright & Permissions.
  2121. * cropmarks:                            Cropmarks and Magnification.
  2122. * defcodeindex:                         New Indices.
  2123. * defcv:                                Abstract Objects.
  2124. * deffn:                                Functions Commands.
  2125. * deffnx:                               deffnx.
  2126. * defindex:                             New Indices.
  2127. * defivar:                              Abstract Objects.
  2128. * defmac:                               Functions Commands.
  2129. * defmethod:                            Abstract Objects.
  2130. * defop:                                Abstract Objects.
  2131. * defopt:                               Variables Commands.
  2132. * defspec:                              Functions Commands.
  2133. * deftp:                                Data Types.
  2134. * deftypefn:                            Typed Functions.
  2135. * deftypefun:                           Typed Functions.
  2136. * deftypevar:                           Typed Variables.
  2137. * deftypevr:                            Typed Variables.
  2138. * defun:                                Functions Commands.
  2139. * defvar:                               Variables Commands.
  2140. * defvr:                                Variables Commands.
  2141. * dfn:                                  dfn.
  2142. * display:                              display.
  2143. * dmn:                                  dmn.
  2144. * dots:                                 dots.
  2145. * emph:                                 emph & strong.
  2146. * end:                                  Quotations and Examples.
  2147. * end:                                  Introducing Lists.
  2148. * end titlepage:                        end titlepage.
  2149. * enumerate:                            enumerate.
  2150. * evenfooting:                          Custom Headings.
  2151. * evenheading:                          Custom Headings.
  2152. * everyfooting:                         Custom Headings.
  2153. * everyheading:                         Custom Headings.
  2154. * example:                              example.
  2155. * exdent:                               exdent.
  2156. * file:                                 file.
  2157. * filll:                                Copyright & Permissions.
  2158. * finalout:                             Overfull hboxes.
  2159. * findex:                               Indexing Commands.
  2160. * flushleft:                            flushleft & flushright.
  2161. * flushright:                           flushleft & flushright.
  2162. * foobar:                               Optional Arguments.
  2163. * footnote:                             Footnotes.
  2164. * footnotestyle:                        Footnotes.
  2165. * format:                               format.
  2166. * forward-word:                         Def Cmd Template.
  2167. * ftable:                               ftable vtable.
  2168. * group:                                group.
  2169. * heading:                              unnumberedsec appendixsec heading.
  2170. * headings:                             headings on off.
  2171. * i (italic font):                      Fonts.
  2172. * ifclear:                              ifset ifclear.
  2173. * ifinfo:                               Conditionals.
  2174. * ifset:                                ifset ifclear.
  2175. * iftex:                                Conditionals.
  2176. * ignore:                               Comments.
  2177. * include:                              Using Include Files.
  2178. * Info-validate:                        Running Info-Validate.
  2179. * INFOPATH:                             Other Info Directories.
  2180. * inforef:                              inforef.
  2181. * input (TeX command):                  Minimum.
  2182. * isearch-backward:                     deffnx.
  2183. * isearch-forward:                      deffnx.
  2184. * item:                                 itemize.
  2185. * item:                                 table.
  2186. * itemize:                              itemize.
  2187. * itemx:                                itemx.
  2188. * kbd:                                  kbd.
  2189. * key:                                  key.
  2190. * kindex:                               Indexing Commands.
  2191. * lisp:                                 Lisp Example.
  2192. * lpr (DVI print command):              Shell Format & Print.
  2193. * mag (TeX command):                    Cropmarks and Magnification.
  2194. * majorheading:                         majorheading & chapheading.
  2195. * makeinfo-buffer:                      makeinfo in Emacs.
  2196. * makeinfo-kill-job:                    makeinfo in Emacs.
  2197. * makeinfo-recenter-output-buffer:      makeinfo in Emacs.
  2198. * makeinfo-region:                      makeinfo in Emacs.
  2199. * menu:                                 Menus.
  2200. * minus:                                minus.
  2201. * need:                                 need.
  2202. * next-error:                           makeinfo in Emacs.
  2203. * noindent:                             noindent.
  2204. * occur:                                Using occur.
  2205. * occur-mode-goto-occurrence:           Showing the Structure.
  2206. * oddfooting:                           Custom Headings.
  2207. * oddheading:                           Custom Headings.
  2208. * page:                                 page.
  2209. * page-delimiter:                       Showing the Structure.
  2210. * paragraphindent:                      paragraphindent.
  2211. * pindex:                               Indexing Commands.
  2212. * printindex:                           Printing Indices & Menus.
  2213. * pxref:                                pxref.
  2214. * quotation:                            quotation.
  2215. * r (Roman font):                       Fonts.
  2216. * ref:                                  ref.
  2217. * refill:                               Refilling Paragraphs.
  2218. * samp:                                 samp.
  2219. * sc (small caps font):                 Smallcaps.
  2220. * section:                              section.
  2221. * set:                                  ifset ifclear.
  2222. * setchapternewpage:                    setchapternewpage.
  2223. * setfilename:                          setfilename.
  2224. * settitle:                             settitle.
  2225. * shortcontents:                        Contents.
  2226. * smallbook:                            smallbook.
  2227. * smallexample:                         smallexample & smalllisp.
  2228. * smalllisp:                            smallexample & smalllisp.
  2229. * sp (line spacing):                    sp.
  2230. * sp (titlepage line spacing):          titlefont center sp.
  2231. * strong:                               emph & strong.
  2232. * subheading:                           unnumberedsubsec appendixsubsec subheading.
  2233. * subsection:                           subsection.
  2234. * subsubheading:                        subsubsection.
  2235. * subsubsection:                        subsubsection.
  2236. * subtitle:                             title subtitle author.
  2237. * summarycontents:                      Contents.
  2238. * syncodeindex:                         syncodeindex.
  2239. * syncodeindex:                         syncodeindex.
  2240. * synindex:                             synindex.
  2241. * t (typewriter font):                  Fonts.
  2242. * table:                                Two-column Tables.
  2243. * tex:                                  Using Ordinary TeX Commands.
  2244. * tex (command):                        tex.
  2245. * texi2dvi (shell script):              Shell Format & Print.
  2246. * texindex:                             Format/Print Hardcopy.
  2247. * texindex:                             Shell Format & Print.
  2248. * texinfo-all-menus-update:             Updating Commands.
  2249. * texinfo-every-node-update:            Updating Commands.
  2250. * texinfo-format-buffer:                Info Formatting.
  2251. * texinfo-format-buffer:                texinfo-format commands.
  2252. * texinfo-format-buffer:                texinfo-format commands.
  2253. * texinfo-format-region:                texinfo-format commands.
  2254. * texinfo-format-region:                texinfo-format commands.
  2255. * texinfo-format-region:                Info Formatting.
  2256. * texinfo-indent-menu-description:      Other Updating Commands.
  2257. * texinfo-insert-@code:                 Inserting.
  2258. * texinfo-insert-@dfn:                  Inserting.
  2259. * texinfo-insert-@end:                  Inserting.
  2260. * texinfo-insert-@example:              Inserting.
  2261. * texinfo-insert-@item:                 Inserting.
  2262. * texinfo-insert-@kbd:                  Inserting.
  2263. * texinfo-insert-@node:                 Inserting.
  2264. * texinfo-insert-@noindent:             Inserting.
  2265. * texinfo-insert-@samp:                 Inserting.
  2266. * texinfo-insert-@table:                Inserting.
  2267. * texinfo-insert-@var:                  Inserting.
  2268. * texinfo-insert-braces:                Inserting.
  2269. * texinfo-insert-node-lines:            Other Updating Commands.
  2270. * texinfo-make-menu:                    Updating Commands.
  2271. * texinfo-master-menu:                  Updating Commands.
  2272. * texinfo-multiple-files-update:        texinfo-multiple-files-update.
  2273. * texinfo-multiple-files-update (in brief): Other Updating Commands.
  2274. * texinfo-sequential-node-update:       Other Updating Commands.
  2275. * texinfo-show-structure:               Using texinfo-show-structure.
  2276. * texinfo-show-structure:               Showing the Structure.
  2277. * texinfo-start-menu-description:       Inserting.
  2278. * texinfo-tex-buffer:                   Printing.
  2279. * texinfo-tex-print:                    Printing.
  2280. * texinfo-tex-region:                   Printing.
  2281. * texinfo-update-node:                  Updating Commands.
  2282. * TEXINPUTS:                            Preparing for TeX.
  2283. * thischapter:                          Custom Headings.
  2284. * thischaptername:                      Custom Headings.
  2285. * thisfile:                             Custom Headings.
  2286. * thispage:                             Custom Headings.
  2287. * thistitle:                            Custom Headings.
  2288. * tindex:                               Indexing Commands.
  2289. * title:                                title subtitle author.
  2290. * titlefont:                            titlefont center sp.
  2291. * titlepage:                            titlepage.
  2292. * today:                                Custom Headings.
  2293. * top (@-command):                      makeinfo top command.
  2294. * unnumbered:                           unnumbered & appendix.
  2295. * unnumberedsec:                        unnumberedsec appendixsec heading.
  2296. * unnumberedsubsec:                     unnumberedsubsec appendixsubsec subheading.
  2297. * unnumberedsubsubsec:                  subsubsection.
  2298. * up-list:                              Inserting.
  2299. * value:                                value.
  2300. * var:                                  var.
  2301. * vindex:                               Indexing Commands.
  2302. * vskip:                                Copyright & Permissions.
  2303. * vtable:                               ftable vtable.
  2304. * w (prevent line break):               w.
  2305. * xref:                                 xref.
  2306. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2307. file texi.texi.
  2308.    This file documents Texinfo, a documentation system that uses a
  2309. single source file to produce both on-line information and a printed
  2310. manual.
  2311.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  2312.    This is the second edition of the Texinfo documentation,
  2313. and is consistent with version 2 of `texinfo.tex'.
  2314.    Permission is granted to make and distribute verbatim copies of this
  2315. manual provided the copyright notice and this permission notice are
  2316. preserved on all copies.
  2317.    Permission is granted to copy and distribute modified versions of
  2318. this manual under the conditions for verbatim copying, provided that
  2319. the entire resulting derived work is distributed under the terms of a
  2320. permission notice identical to this one.
  2321.    Permission is granted to copy and distribute translations of this
  2322. manual into another language, under the above conditions for modified
  2323. versions, except that this permission notice may be stated in a
  2324. translation approved by the Free Software Foundation.
  2325. File: texi.info,  Node: Concept Index,  Prev: Command and Variable Index,  Up: Top
  2326. Concept Index
  2327. *************
  2328. * Menu:
  2329. * @-command in nodename:                Node Line Requirements.
  2330. * @-command list:                       Command List.
  2331. * @-command syntax:                     Command Syntax.
  2332. * @-commands:                           Formatting Commands.
  2333. * .cshrc initialization file:           Preparing for TeX.
  2334. * .profile initialization file:         Preparing for TeX.
  2335. * @include file sample:                 Sample Include File.
  2336. * @menu parts:                          Menu Parts.
  2337. * @node line writing:                   Writing a Node.
  2338. * makeinfo inside Emacs:                makeinfo in Emacs.
  2339. * makeinfo options:                     makeinfo options.
  2340. * TEXINPUTS environment variable:       Preparing for TeX.
  2341. * dir directory for Info installation:  Install an Info File.
  2342. * dir file listing:                     New Info File.
  2343. * End node footnote style:              Footnotes.
  2344. * Separate footnote style:              Footnotes.
  2345. * Top node:                             The Top Node.
  2346. * Top node is first:                    First Node.
  2347. * Top node naming for references:       Top Node Naming.
  2348. * Top node summary:                     Top Node Summary.
  2349. * hboxes, overfull:                     Overfull hboxes.
  2350. * ifinfo permissions:                   ifinfo Permissions.
  2351. * TeX commands, using ordinary:         Using Ordinary TeX Commands.
  2352. * TeX index sorting:                    Format/Print Hardcopy.
  2353. * TeX input initialization:             Preparing for TeX.
  2354. * TeX, how to obtain:                   Obtaining TeX.
  2355. * A4 paper, printing on:                A4 Paper.
  2356. * Abbreviations for keys:               key.
  2357. * Adding a new info file:               New Info File.
  2358. * Alphabetical @-command list:          Command List.
  2359. * Another Info directory:               Other Info Directories.
  2360. * Apostrophe in nodename:               Node Line Requirements.
  2361. * Arguments, repeated and optional:     Optional Arguments.
  2362. * Automatic pointer creation with makeinfo: makeinfo Pointer Creation.
  2363. * Automatically insert nodes, menus:    Updating Nodes and Menus.
  2364. * Badly referenced nodes:               Running Info-Validate.
  2365. * Batch formatting for Info:            Batch Formatting.
  2366. * Beginning a Texinfo file:             Beginning a File.
  2367. * Beginning line of a Texinfo file:     First Line.
  2368. * Black rectangle in hardcopy:          Overfull hboxes.
  2369. * Blank lines:                          sp.
  2370. * Book characteristics, printed:        Printed Books.
  2371. * Book, printing small:                 smallbook.
  2372. * Box with rounded corners:             cartouche.
  2373. * Braces and argument syntax:           Command Syntax.
  2374. * Braces, inserting:                    Braces Atsigns Periods.
  2375. * Braces, when to use:                  Formatting Commands.
  2376. * Breaks in a line:                     Line Breaks.
  2377. * Buffer formatting and printing:       Printing.
  2378. * Bullets, inserting:                   Dots Bullets.
  2379. * Capitalizing index entries:           Indexing Commands.
  2380. * Case in nodename:                     Node Line Requirements.
  2381. * Catching errors with TeX formatting:  Debugging with TeX.
  2382. * Catching errors with Info formatting: Debugging with Info.
  2383. * Catching mistakes:                    Catching Mistakes.
  2384. * Chapter structuring:                  Structuring.
  2385. * Characteristics, printed books or manuals: Printed Books.
  2386. * Checking for badly referenced nodes:  Running Info-Validate.
  2387. * Colon in nodename:                    Node Line Requirements.
  2388. * Combining indices:                    Combining Indices.
  2389. * Comma in nodename:                    Node Line Requirements.
  2390. * Command definitions:                  Sample Function Definition.
  2391. * Commands to insert single characters: Braces Atsigns Periods.
  2392. * Commands using ordinary TeX:          Using Ordinary TeX Commands.
  2393. * Commands, inserting them:             Inserting.
  2394. * Comments:                             Comments.
  2395. * Compile command for formatting:       Compile-Command.
  2396. * Conditionally visible text:           Conditionals.
  2397. * Conditions for copying Texinfo:       Copying.
  2398. * Contents, Table of:                   Contents.
  2399. * Contents-like outline of file structure: Showing the Structure.
  2400. * Conventions for writing definitions:  Def Cmd Conventions.
  2401. * Conventions, syntactic:               Conventions.
  2402. * Copying conditions:                   Copying.
  2403. * Copying permissions:                  Sample Permissions.
  2404. * Copying software:                     Software Copying Permissions.
  2405. * Copyright page:                       Copyright & Permissions.
  2406. * Correcting mistakes:                  Catching Mistakes.
  2407. * Create nodes, menus automatically:    Updating Nodes and Menus.
  2408. * Creating an Info file:                Create an Info File.
  2409. * Creating an unsplit file:             Unsplit.
  2410. * Creating index entries:               Indexing Commands.
  2411. * Creating indices:                     Indices.
  2412. * Creating pointers with makeinfo:      makeinfo Pointer Creation.
  2413. * Cropmarks for printing:               Cropmarks and Magnification.
  2414. * Cross reference parts:                Cross Reference Parts.
  2415. * Cross references:                     Cross References.
  2416. * Cross references using @inforef:      inforef.
  2417. * Cross references using @pxref:        pxref.
  2418. * Cross references using @ref:          ref.
  2419. * Cross references using @xref:         xref.
  2420. * Debugging the Texinfo structure:      Catching Mistakes.
  2421. * Debugging with TeX formatting:        Debugging with TeX.
  2422. * Debugging with Info formatting:       Debugging with Info.
  2423. * Defining indexing entries:            Indexing Commands.
  2424. * Defining new indices:                 New Indices.
  2425. * Definition commands:                  Definition Commands.
  2426. * Definition conventions:               Def Cmd Conventions.
  2427. * Definition template:                  Def Cmd Template.
  2428. * Definitions grouped together:         deffnx.
  2429. * Description for menu, start:          Inserting.
  2430. * Different cross reference commands:   Cross Reference Commands.
  2431. * Dimension formatting:                 dmn.
  2432. * Display formatting:                   display.
  2433. * Distribution:                         Software Copying Permissions.
  2434. * Dots, inserting:                      Dots Bullets.
  2435. * Dots, inserting:                      dots.
  2436. * Double-colon menu entries:            Less Cluttered Menu Entry.
  2437. * DVI file:                             Shell Format & Print.
  2438. * Ellipsis, inserting:                  Dots Bullets.
  2439. * Emacs:                                Texinfo Mode.
  2440. * Emacs shell, format, print from:      Within Emacs.
  2441. * Emphasizing text:                     Emphasis.
  2442. * Emphasizing text, font for:           emph & strong.
  2443. * End of header line:                   End of Header.
  2444. * End titlepage starts headings:        end titlepage.
  2445. * Ending a Texinfo file:                Ending a File.
  2446. * Entries for an index:                 Indexing Commands.
  2447. * Entries, making index:                Index Entries.
  2448. * Enumeration:                          enumerate.
  2449. * Equivalence, indicating it:           Equivalence.
  2450. * Error message, indicating it:         Error Glyph.
  2451. * Errors, parsing:                      makeinfo in Emacs.
  2452. * European A4 paper:                    A4 Paper.
  2453. * Evaluation glyph:                     result.
  2454. * Example for a small book:             smallexample & smalllisp.
  2455. * Example menu:                         Menu Example.
  2456. * Examples, formatting them:            example.
  2457. * Expansion, indicating it:             expansion.
  2458. * File beginning:                       Beginning a File.
  2459. * File ending:                          Ending a File.
  2460. * File section structure, showing it:   Showing the Structure.
  2461. * Filling paragraphs:                   Refilling Paragraphs.
  2462. * Final output:                         Overfull hboxes.
  2463. * Finding badly referenced nodes:       Running Info-Validate.
  2464. * First line of a Texinfo file:         First Line.
  2465. * First node:                           First Node.
  2466. * Fonts for indices:                    syncodeindex.
  2467. * Fonts for printing, not for Info:     Fonts.
  2468. * Footings:                             Headings.
  2469. * Footnotes:                            Footnotes.
  2470. * Format a dimension:                   dmn.
  2471. * Format and print hardcopy:            Format/Print Hardcopy.
  2472. * Format and print in Texinfo mode:     Texinfo Mode Printing.
  2473. * Format with the compile command:      Compile-Command.
  2474. * Format, print from Emacs shell:       Within Emacs.
  2475. * Formatting a file for Info:           Create an Info File.
  2476. * Formatting commands:                  Formatting Commands.
  2477. * Formatting examples:                  example.
  2478. * Formatting for Info:                  Info Formatting.
  2479. * Formatting for printing:              Printing.
  2480. * Formatting headings and footings:     Headings.
  2481. * Formatting requirements:              Requirements Summary.
  2482. * Frequently used commands, inserting:  Inserting.
  2483. * Function definitions:                 Sample Function Definition.
  2484. * General syntactic conventions:        Conventions.
  2485. * Generating menus with indices:        Printing Indices & Menus.
  2486. * Glyphs:                               Glyphs.
  2487. * GNU Emacs:                            Texinfo Mode.
  2488. * GNU Emacs shell, format, print from:  Within Emacs.
  2489. * Going to other Info files' nodes:     Other Info Files.
  2490. * Group (hold text together vertically): group.
  2491. * Grouping two definitions together:    deffnx.
  2492. * Hardcopy, printing it:                Format/Print Hardcopy.
  2493. * Header for Texinfo files:             Header.
  2494. * Header of a Texinfo file:             First Line.
  2495. * Headings:                             Headings.
  2496. * Headings, page, begin to appear:      end titlepage.
  2497. * Highlighting text:                    Indicating.
  2498. * Hints:                                Tips.
  2499. * Holding text together vertically:     group.
  2500. * If text conditionally visible:        Conditionals.
  2501. * Ignored text:                         Comments.
  2502. * Include file requirements:            Include File Requirements.
  2503. * Include file sample:                  Sample Include File.
  2504. * Include files:                        Include Files.
  2505. * Indentation undoing:                  exdent.
  2506. * Indenting paragraphs:                 paragraphindent.
  2507. * Index entries:                        Indexing Commands.
  2508. * Index entries, making:                Index Entries.
  2509. * Index entry capitalization:           Indexing Commands.
  2510. * Index font types:                     Indexing Commands.
  2511. * Indexing commands, predefined:        Indexing Commands.
  2512. * Indexing table entries automatically: ftable vtable.
  2513. * Indicating commands, definitions, etc.: Indicating.
  2514. * Indicating evaluation:                result.
  2515. * Indices:                              Indices.
  2516. * Indices, combining them:              Combining Indices.
  2517. * Indices, defining new:                New Indices.
  2518. * Indices, printing and menus:          Printing Indices & Menus.
  2519. * Indices, sorting:                     Format/Print Hardcopy.
  2520. * Indices, two letter names:            syncodeindex.
  2521. * Indirect subfiles:                    Tag and Split Files.
  2522. * Info batch formatting:                Batch Formatting.
  2523. * Info file installation:               Install an Info File.
  2524. * Info file requires @setfilename:      setfilename.
  2525. * Info file, listing new one:           New Info File.
  2526. * Info file, splitting manually:        Splitting.
  2527. * Info files:                           Info Files.
  2528. * Info formatting:                      Info Formatting.
  2529. * Info installed in another directory:  Other Info Directories.
  2530. * Info validating a large file:         Using Info-validate.
  2531. * Info, creating an on-line file:       Create an Info File.
  2532. * Info; other files' nodes:             Other Info Files.
  2533. * Initialization file for TeX input:    Preparing for TeX.
  2534. * Insert nodes, menus automatically:    Updating Nodes and Menus.
  2535. * Inserting @, braces, and periods:     Braces Atsigns Periods.
  2536. * Inserting dots:                       Dots Bullets.
  2537. * Inserting dots:                       dots.
  2538. * Inserting ellipsis:                   Dots Bullets.
  2539. * Inserting frequently used commands:   Inserting.
  2540. * Inserting special characters and symbols: Insertions.
  2541. * Installing an Info file:              Install an Info File.
  2542. * Installing Info in another directory: Other Info Directories.
  2543. * Introduction, as part of file:        Software Copying Permissions.
  2544. * Itemization:                          itemize.
  2545. * Keys, recommended names:              key.
  2546. * Larger or smaller pages:              Cropmarks and Magnification.
  2547. * Less cluttered menu entry:            Less Cluttered Menu Entry.
  2548. * License agreement:                    Software Copying Permissions.
  2549. * Line breaks:                          Line Breaks.
  2550. * Line breaks, preventing:              w.
  2551. * Line spacing:                         sp.
  2552. * Lisp example:                         Lisp Example.
  2553. * Lisp example for a small book:        smallexample & smalllisp.
  2554. * List of  @-commands:                  Command List.
  2555. * Listing a new info file:              New Info File.
  2556. * Lists and tables, making them:        Lists and Tables.
  2557. * Local variables:                      Compile-Command.
  2558. * Location of menus:                    Menu Location.
  2559. * Looking for badly referenced nodes:   Running Info-Validate.
  2560. * Macro definitions:                    Sample Function Definition.
  2561. * Magnified printing:                   Cropmarks and Magnification.
  2562. * Making a printed manual:              Format/Print Hardcopy.
  2563. * Making a tag table automatically:     Tag and Split Files.
  2564. * Making a tag table manually:          Unsplit.
  2565. * Making cross references:              Cross References.
  2566. * Making line and page breaks:          Breaks.
  2567. * Making lists and tables:              Lists and Tables.
  2568. * Manual characteristics, printed:      Printed Books.
  2569. * Marking text within a paragraph:      Marking Text.
  2570. * Marking words and phrases:            Marking Text.
  2571. * Master menu:                          The Top Node.
  2572. * Master menu parts:                    Master Menu Parts.
  2573. * Mathematical expressions:             Using Ordinary TeX Commands.
  2574. * Menu description, start:              Inserting.
  2575. * Menu entries with two colons:         Less Cluttered Menu Entry.
  2576. * Menu example:                         Menu Example.
  2577. * Menu location:                        Menu Location.
  2578. * Menu parts:                           Menu Parts.
  2579. * Menu writing:                         Writing a Menu.
  2580. * Menus:                                Menus.
  2581. * Menus generated with indices:         Printing Indices & Menus.
  2582. * META key:                             key.
  2583. * Meta-syntactic chars for arguments:   Optional Arguments.
  2584. * Minimal Texinfo file (requirements):  Minimum.
  2585. * Mistakes, catching:                   Catching Mistakes.
  2586. * Mode, using Texinfo:                  Texinfo Mode.
  2587. * Must have in Texinfo file:            Minimum.
  2588. * Names for indices:                    syncodeindex.
  2589. * Names recommended for keys:           key.
  2590. * Naming a `Top' Node in references:    Top Node Naming.
  2591. * Need space at page bottom:            need.
  2592. * New index defining:                   New Indices.
  2593. * New info file, listing it in dir file: New Info File.
  2594. * Node line requirements:               Node Line Requirements.
  2595. * Node line writing:                    Writing a Node.
  2596. * Node, defined:                        node.
  2597. * Node, `Top':                          The Top Node.
  2598. * Nodename must be unique:              Node Line Requirements.
  2599. * Nodename, cannot contain:             Node Line Requirements.
  2600. * Nodes for menus are short:            Menu Location.
  2601. * Nodes in other Info files:            Other Info Files.
  2602. * Nodes, catching mistakes:             Catching Mistakes.
  2603. * Nodes, checking for badly referenced: Running Info-Validate.
  2604. * Obtaining TeX:                        Obtaining TeX.
  2605. * Occurrences, listing with @occur:     Using occur.
  2606. * Optional and repeated arguments:      Optional Arguments.
  2607. * Options for makeinfo:                 makeinfo options.
  2608. * Ordinary TeX commands, using:         Using Ordinary TeX Commands.
  2609. * Other Info files' nodes:              Other Info Files.
  2610. * Outline of file structure, showing it: Showing the Structure.
  2611. * Overfull hboxes:                      Overfull hboxes.
  2612. * Overview of Texinfo:                  Overview.
  2613. * Page breaks:                          page.
  2614. * Page delimiter in Texinfo mode:       Showing the Structure.
  2615. * Page headings:                        Headings.
  2616. * Page numbering:                       Headings.
  2617. * Page sizes for books:                 smallbook.
  2618. * Pages, starting odd:                  setchapternewpage.
  2619. * Paper size, European A4:              A4 Paper.
  2620. * Paragraph indentation:                paragraphindent.
  2621. * Paragraph, marking text within:       Marking Text.
  2622. * Parsing errors:                       makeinfo in Emacs.
  2623. * Part of file formatting and printing: Printing.
  2624. * Parts of a cross reference:           Cross Reference Parts.
  2625. * Parts of a master menu:               Master Menu Parts.
  2626. * Parts of a menu:                      Menu Parts.
  2627. * Periods, inserting:                   Braces Atsigns Periods.
  2628. * Permissions:                          Sample Permissions.
  2629. * Permissions, printed:                 Copyright & Permissions.
  2630. * PlainTeX:                             Using Ordinary TeX Commands.
  2631. * Point, indicating it in a buffer:     Point Glyph.
  2632. * Pointer creation with makeinfo:       makeinfo Pointer Creation.
  2633. * Pointer validation with makeinfo:     Pointer Validation.
  2634. * Predefined indexing commands:         Indexing Commands.
  2635. * Predefined names for indices:         syncodeindex.
  2636. * Preparing to use TeX:                 Preparing for TeX.
  2637. * Preventing line and page breaks:      Breaks.
  2638. * Print and format in Texinfo mode:     Texinfo Mode Printing.
  2639. * Print, format from Emacs shell:       Within Emacs.
  2640. * Printed book and manual characteristics: Printed Books.
  2641. * Printed output, indicating it:        Print Glyph.
  2642. * Printed permissions:                  Copyright & Permissions.
  2643. * Printing a region or buffer:          Printing.
  2644. * Printing an index:                    Printing Indices & Menus.
  2645. * Printing cropmarks:                   Cropmarks and Magnification.
  2646. * Problems, catching:                   Catching Mistakes.
  2647. * Quotations:                           quotation.
  2648. * Recommended names for keys:           key.
  2649. * Rectangle, ugly, black in hardcopy:   Overfull hboxes.
  2650. * References:                           Cross References.
  2651. * References using @inforef:            inforef.
  2652. * References using @pxref:              pxref.
  2653. * References using @ref:                ref.
  2654. * References using @xref:               xref.
  2655. * Referring to other Info files:        Other Info Files.
  2656. * Refilling paragraphs:                 Refilling Paragraphs.
  2657. * Region formatting and printing:       Printing.
  2658. * Region printing in Texinfo mode:      Texinfo Mode Printing.
  2659. * Repeated and optional arguments:      Optional Arguments.
  2660. * Required in Texinfo file:             Minimum.
  2661. * Requirements for formatting:          Requirements Summary.
  2662. * Requirements for include files:       Include File Requirements.
  2663. * Requirements for updating commands:   Updating Requirements.
  2664. * Result of an expression:              result.
  2665. * Running Info-validate:                Using Info-validate.
  2666. * Running makeinfo in Emacs:            makeinfo in Emacs.
  2667. * Running an Info formatter:            Info Formatting.
  2668. * Sample @include file:                 Sample Include File.
  2669. * Sample function definition:           Sample Function Definition.
  2670. * Sample Texinfo file:                  Short Sample.
  2671. * Sample Texinfo file, no comments:     Sample Texinfo File.
  2672. * Section structure of a file, showing it: Showing the Structure.
  2673. * Shell, format, print from:            Within Emacs.
  2674. * Shell, running makeinfo in:           makeinfo in Emacs.
  2675. * Short nodes for menus:                Menu Location.
  2676. * Showing the section structure of a file: Showing the Structure.
  2677. * Showing the structure of a file:      Using texinfo-show-structure.
  2678. * Single characters, commands to insert: Braces Atsigns Periods.
  2679. * Size of printed book:                 smallbook.
  2680. * Small book example:                   smallexample & smalllisp.
  2681. * Small book size:                      smallbook.
  2682. * Small caps font:                      Smallcaps.
  2683. * Software copying permissions:         Software Copying Permissions.
  2684. * Sorting indices:                      Format/Print Hardcopy.
  2685. * Spaces (blank lines):                 sp.
  2686. * Special insertions:                   Insertions.
  2687. * Special typesetting commands:         Dots Bullets.
  2688. * Specifying index entries:             Indexing Commands.
  2689. * Splitting an Info file manually:      Splitting.
  2690. * Start of header line:                 Start of Header.
  2691. * Starting chapters:                    setchapternewpage.
  2692. * Structure of a file, showing it:      Showing the Structure.
  2693. * Structure, catching mistakes in:      Catching Mistakes.
  2694. * Structuring of chapters:              Structuring.
  2695. * Subsection-like commands:             unnumberedsubsec appendixsubsec subheading.
  2696. * Subsub commands:                      subsubsection.
  2697. * Syntactic conventions:                Conventions.
  2698. * Syntax, optional & repeated arguments: Optional Arguments.
  2699. * Table of contents:                    Contents.
  2700. * Tables and lists, making them:        Lists and Tables.
  2701. * Tables with indexes:                  ftable vtable.
  2702. * Tables, making two-column:            Two-column Tables.
  2703. * Tabs; don't use!:                     Conventions.
  2704. * Tag table, making automatically:      Tag and Split Files.
  2705. * Tag table, making manually:           Unsplit.
  2706. * Template for a definition:            Def Cmd Template.
  2707. * Texinfo file beginning:               Beginning a File.
  2708. * Texinfo file ending:                  Ending a File.
  2709. * Texinfo file header:                  Header.
  2710. * Texinfo file minimum:                 Minimum.
  2711. * Texinfo file section structure, showing it: Showing the Structure.
  2712. * Texinfo mode:                         Texinfo Mode.
  2713. * Texinfo overview:                     Overview.
  2714. * Texinfo printed book characteristics: Printed Books.
  2715. * Text, conditionally visible:          Conditionals.
  2716. * Thin space between number, dimension: dmn.
  2717. * Tips:                                 Tips.
  2718. * Title page:                           titlepage.
  2719. * Titlepage end starts headings:        end titlepage.
  2720. * Titlepage permissions:                Titlepage Permissions.
  2721. * Tree structuring:                     Tree Structuring.
  2722. * Two letter names for indices:         syncodeindex.
  2723. * Two named items for @table:           itemx.
  2724. * Two part menu entry:                  Less Cluttered Menu Entry.
  2725. * Two `First' Lines for @deffn:         deffnx.
  2726. * Typesetting commands for dots, etc.:  Dots Bullets.
  2727. * Uncluttered menu entry:               Less Cluttered Menu Entry.
  2728. * Unique nodename requirement:          Node Line Requirements.
  2729. * Unprocessed text:                     Comments.
  2730. * Unsplit file creation:                Unsplit.
  2731. * Updating nodes and menus:             Updating Nodes and Menus.
  2732. * Updating requirements:                Updating Requirements.
  2733. * Usage tips:                           Tips.
  2734. * Validating a large file:              Using Info-validate.
  2735. * Validation of pointers:               Pointer Validation.
  2736. * Value of an expression, indicating:   result.
  2737. * Vertical whitespace (vskip):          Copyright & Permissions.
  2738. * Vertically holding text together:     group.
  2739. * Visibility of conditional text:       Conditionals.
  2740. * Words and phrases, marking them:      Marking Text.
  2741. * Writing a menu:                       Writing a Menu.
  2742. * Writing an @node line:                Writing a Node.
  2743. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2744. file texi.texi.
  2745.    This file documents Texinfo, a documentation system that uses a
  2746. single source file to produce both on-line information and a printed
  2747. manual.
  2748.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  2749.    This is the second edition of the Texinfo documentation,
  2750. and is consistent with version 2 of `texinfo.tex'.
  2751.    Permission is granted to make and distribute verbatim copies of this
  2752. manual provided the copyright notice and this permission notice are
  2753. preserved on all copies.
  2754.    Permission is granted to copy and distribute modified versions of
  2755. this manual under the conditions for verbatim copying, provided that
  2756. the entire resulting derived work is distributed under the terms of a
  2757. permission notice identical to this one.
  2758.    Permission is granted to copy and distribute translations of this
  2759. manual into another language, under the above conditions for modified
  2760. versions, except that this permission notice may be stated in a
  2761. translation approved by the Free Software Foundation.
  2762. File: texi.info,  Node: Texinfo Mode,  Next: Beginning a File,  Prev: Overview,  Up: Top
  2763. Using Texinfo Mode
  2764. ******************
  2765.    You may edit a Texinfo file with any text editor you choose.  A
  2766. Texinfo file is no different from any other ASCII file.  However, GNU
  2767. Emacs comes with a special mode, called Texinfo mode, that provides
  2768. Emacs commands and tools to help ease your work.
  2769.    This chapter describes features of GNU Emacs' Texinfo mode but not
  2770. any features of the Texinfo formatting language.  If you are reading
  2771. this manual straight through from the beginning, you may want to skim
  2772. through this chapter briefly and come back to it after reading
  2773. succeeding chapters which describe the Texinfo formatting language in
  2774. detail.
  2775. * Menu:
  2776. * Texinfo Mode Overview::       How Texinfo mode can help you.
  2777. * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
  2778.                                   purpose editing features.
  2779. * Inserting::                   How to insert frequently used @-commands.
  2780. * Showing the Structure::       How to show the structure of a file.
  2781. * Updating Nodes and Menus::    How to update or create new nodes and menus.
  2782. * Info Formatting::             How to format for Info.
  2783. * Printing::                    How to format and print part or all of a file.
  2784. * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
  2785. File: texi.info,  Node: Texinfo Mode Overview,  Next: Emacs Editing,  Up: Texinfo Mode
  2786. Texinfo Mode Overview
  2787. =====================
  2788.    Texinfo mode provides special features for working with Texinfo
  2789. files:
  2790.    * Insert frequently used @commands.
  2791.    * Automatically create `@node' lines.
  2792.    * Show the structure of a Texinfo source file.
  2793.    * Automatically create or update the `Next',
  2794.      `Previous', and `Up' pointers of a node.
  2795.    * Automatically create or update menus.
  2796.    * Automatically create a master menu.
  2797.    * Format a part or all of a file for Info.
  2798.    * Typeset and print part or all of a file.
  2799.    Perhaps the two most helpful features are those for inserting
  2800. frequently used @-commands and for creating node pointers and menus.
  2801. File: texi.info,  Node: Emacs Editing,  Next: Inserting,  Prev: Texinfo Mode Overview,  Up: Texinfo Mode
  2802. The Usual GNU Emacs Editing Commands
  2803. ====================================
  2804.    In most cases, the usual Text mode commands work the same in Texinfo
  2805. mode as they do in Text mode.  Texinfo mode adds new editing commands
  2806. and tools to GNU Emacs' general purpose editing features.  The major
  2807. difference concerns filling.  In Texinfo mode, the paragraph separation
  2808. variable and syntax table are redefined so that Texinfo commands that
  2809. should be on lines of their own are not inadvertently included in
  2810. paragraphs.  Thus, the `M-q' (`fill-paragraph') command will refill a
  2811. paragraph but not mix an indexing command on a line adjacent to it into
  2812. the paragraph.
  2813.    In addition, Texinfo mode sets the `page-delimiter' variable to the
  2814. value of `texinfo-chapter-level-regexp'; by default, this is a regular
  2815. expression matching the commands for chapters and their equivalents,
  2816. such as appendices.  With this value for the page delimiter, you can
  2817. jump from chapter title to chapter title with the `C-x ]'
  2818. (`forward-page') and `C-x [' (`backward-page') commands and narrow to a
  2819. chapter with the `C-x p' (`narrow-to-page') command.  (*Note Pages:
  2820. (emacs)Pages, for details about the page commands.)
  2821.    You may name a Texinfo file however you wish, but the convention is
  2822. to end a Texinfo file name with one of the three extensions `.texinfo',
  2823. `.texi', or `.tex'.  A longer extension is preferred, since it is
  2824. explicit, but a shorter extension may be necessary for operating
  2825. systems that limit the length of file names.  GNU Emacs automatically
  2826. enters Texinfo mode when you visit a file with a `.texinfo' or  `.texi'
  2827. extension.  Also, Emacs switches to Texinfo mode when you visit a file
  2828. that has `-*-texinfo-*-' in its first line.  If ever you are in another
  2829. mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
  2830.    Like all other Emacs features, you can customize or enhance Texinfo
  2831. mode as you wish.  In particular, the keybindings are very easy to
  2832. change.  The keybindings described here are the default or standard
  2833. ones.
  2834. File: texi.info,  Node: Inserting,  Next: Showing the Structure,  Prev: Emacs Editing,  Up: Texinfo Mode
  2835. Inserting Frequently Used Commands
  2836. ==================================
  2837.    Texinfo mode provides commands to insert various frequently used
  2838. @-commands into the buffer.  You can use these commands to save
  2839. keystrokes.
  2840.    The insert commands are invoked by typing `C-c' twice and then the
  2841. first letter of the @-command:
  2842. `C-c C-c c'
  2843. `M-x texinfo-insert-@code'
  2844.      Insert `@code{}' and put the cursor between the braces.
  2845. `C-c C-c d'
  2846. `M-x texinfo-insert-@dfn'
  2847.      Insert `@dfn{}' and put the cursor between the braces.
  2848. `C-c C-c e'
  2849. `M-x texinfo-insert-@end'
  2850.      Insert `@end' and attempt to insert the correct following word,
  2851.      such as `example' or `table'.  (This command does not handle
  2852.      nested lists correctly, but inserts the word appropriate to the
  2853.      immediately preceding list.)
  2854. `C-c C-c i'
  2855. `M-x texinfo-insert-@item'
  2856.      Insert `@item' and put the cursor at the beginning of the next
  2857.      line.
  2858. `C-c C-c k'
  2859. `M-x texinfo-insert-@kbd'
  2860.      Insert `@kbd{}' and put the cursor between the braces.
  2861. `C-c C-c n'
  2862. `M-x texinfo-insert-@node'
  2863.      Insert `@node' and a comment line listing the sequence for the
  2864.      `Next', `Previous', and `Up' nodes.  Leave point after the `@node'.
  2865. `C-c C-c o'
  2866. `M-x texinfo-insert-@noindent'
  2867.      Insert `@noindent' and put the cursor at the beginning of the next
  2868.      line.
  2869. `C-c C-c s'
  2870. `M-x texinfo-insert-@samp'
  2871.      Insert `@samp{}' and put the cursor between the braces.
  2872. `C-c C-c t'
  2873. `M-x texinfo-insert-@table'
  2874.      Insert `@table' followed by a SPC and leave the cursor after the
  2875.      SPC.
  2876. `C-c C-c v'
  2877. `M-x texinfo-insert-@var'
  2878.      Insert `@var{}' and put the cursor between the braces.
  2879. `C-c C-c x'
  2880. `M-x texinfo-insert-@example'
  2881.      Insert `@example' and put the cursor at the beginning of the next
  2882.      line.
  2883. `C-c C-c {'
  2884. `M-x texinfo-insert-braces'
  2885.      Insert `{}' and put the cursor between the braces.
  2886. `C-c C-c }'
  2887. `C-c C-c ]'
  2888. `M-x up-list'
  2889.      Move from between a pair of braces forward past the closing brace.
  2890.      Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
  2891.      however, more mnemonic; hence the two keybindings.  (Also, you can
  2892.      move out from between braces by typing `C-f'.)
  2893.    To put a command such as `@code{...}' around an *existing* word,
  2894. position the cursor in front of the word and type `C-u 1 C-c C-c c'.
  2895. This makes it easy to edit existing plain text.  The value of the
  2896. prefix argument tells Emacs how many words following point to include
  2897. between braces--1 for one word, 2 for two words, and so on.  Use a
  2898. negative argument to enclose the previous word or words.  If you do not
  2899. specify a prefix argument, Emacs inserts the @-command string and
  2900. positions the cursor between the braces.  This feature works only for
  2901. those @-commands that operate on a word or words within one line, such
  2902. as `@kbd' and `@var'.
  2903.    This set of insert commands was created after analyzing the frequency
  2904. with which different @-commands are used in the `GNU Emacs Manual' and
  2905. the `GDB Manual'.  If you wish to add your own insert commands, you can
  2906. bind a keyboard macro to a key, use abbreviations, or extend the code
  2907. in `texinfo.el'.
  2908.    `C-c C-c C-d' (`texinfo-start-menu-description') is an insert
  2909. command that works differently from the other insert commands.  It
  2910. inserts a node's section or chapter title in the space for the
  2911. description in a menu entry line.  (A menu entry has three parts, the
  2912. entry name, the node name, and the description.  Only the node name is
  2913. required, but a description helps explain what the node is about.
  2914. *Note The Parts of a Menu: Menu Parts.)
  2915.    To use `texinfo-start-menu-description', position point in a menu
  2916. entry line and type `C-c C-c C-d'.  The command looks for and copies
  2917. the title that goes with the node name, and inserts the title as a
  2918. description; it positions point at beginning of the inserted text so you
  2919. can edit it.  The function does not insert the title if the menu entry
  2920. line already contains a description.
  2921.    This command is only an aid to writing descriptions; it does not do
  2922. the whole job.  You must edit the inserted text since a title tends to
  2923. use the same words as a node name but a useful description uses
  2924. different words.
  2925. File: texi.info,  Node: Showing the Structure,  Next: Updating Nodes and Menus,  Prev: Inserting,  Up: Texinfo Mode
  2926. Showing the Section Structure of a File
  2927. =======================================
  2928.    You can show the section structure of a Texinfo file by using the
  2929. `C-c C-s' command (`texinfo-show-structure').  This command shows the
  2930. section structure of a Texinfo file by listing the lines that begin
  2931. with the @-commands for `@chapter', `@section', and the like.  It
  2932. constructs what amounts to a table of contents.  These lines are
  2933. displayed in another buffer called the `*Occur*' buffer.  In that
  2934. buffer, you can position the cursor over one of the lines and use the
  2935. `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
  2936. corresponding spot in the Texinfo file.
  2937. `C-c C-s'
  2938. `M-x texinfo-show-structure'
  2939.      Show the `@chapter', `@section', and such lines of a Texinfo file.
  2940. `C-c C-c'
  2941. `M-x occur-mode-goto-occurrence'
  2942.      Go to the line in the Texinfo file corresponding to the line under
  2943.      the cursor in the `*Occur*' buffer.
  2944.    If you call `texinfo-show-structure' with a prefix argument by
  2945. typing `C-u C-c C-s', it will list not only those lines with the
  2946. @-commands for `@chapter', `@section', and the like, but also the
  2947. `@node' lines.  (This is how the `texinfo-show-structure' command
  2948. worked without an argument in the first version of Texinfo.  It was
  2949. changed because `@node' lines clutter up the `*Occur*' buffer and are
  2950. usually not needed.)  You can use `texinfo-show-structure' with a prefix
  2951. argument to check whether the `Next', `Previous', and `Up' pointers of
  2952. an `@node' line are correct.
  2953.    Often, when you are working on a manual, you will be interested only
  2954. in the structure of the current chapter.  In this case, you can mark
  2955. off the region of the buffer that you are interested in with the `C-x
  2956. n' (`narrow-to-region') command and `texinfo-show-structure' will work
  2957. on only that region.  To see the whole buffer again, use `C-x w'
  2958. (`widen').  (*Note Narrowing: (emacs)Narrowing, for more information
  2959. about the narrowing commands.)
  2960.    In addition to providing the `texinfo-show-structure' command,
  2961. Texinfo mode sets the value of the page delimiter variable to match the
  2962. chapter-level @-commands.  This enables you to use the `C-x ]'
  2963. (`forward-page') and `C-x [' (`backward-page') commands to move forward
  2964. and backward by chapter, and to use the `C-x p' (`narrow-to-page')
  2965. command to narrow to a chapter.  *Note Pages: (emacs)Pages, for more
  2966. information about the page commands.
  2967. File: texi.info,  Node: Updating Nodes and Menus,  Next: Info Formatting,  Prev: Showing the Structure,  Up: Texinfo Mode
  2968. Updating Nodes and Menus
  2969. ========================
  2970.    Texinfo mode provides commands for automatically creating or updating
  2971. menus and node pointers.  The commands are called "update" commands
  2972. because their most frequent use is for updating a Texinfo file after
  2973. you have worked on it; but you can use them to insert the `Next',
  2974. `Previous', and `Up' pointers into an `@node' line that has none and to
  2975. create menus in a file that has none.
  2976.    If you do not use the updating commands, you need to write menus and
  2977. node pointers by hand, which is a tedious task.
  2978. * Menu:
  2979. * Updating Commands::           Five major updating commands.
  2980. * Updating Requirements::       How to structure a Texinfo file for
  2981.                                   using the updating command.
  2982. * Other Updating Commands::     How to indent descriptions, insert
  2983.                                   missing nodes lines, and update
  2984.                                   nodes in sequence.
  2985. File: texi.info,  Node: Updating Commands,  Next: Updating Requirements,  Up: Updating Nodes and Menus
  2986. The Updating Commands
  2987. ---------------------
  2988.    You can use the updating commands
  2989.    * to insert or update the `Next', `Previous', and `Up' pointers of a
  2990.      node,
  2991.    * to insert or update the menu for a section, and
  2992.    * to create a master menu for a Texinfo source file.
  2993.    You can also use the commands to update all the nodes and menus in a
  2994. region or in a whole Texinfo file.
  2995.    The updating commands work only with conventional Texinfo files,
  2996. which are structured hierarchically like books.  In such files, a
  2997. structuring command line must follow closely after each `@node' line,
  2998. except for the `Top' `@node' line.  (A "structuring command line" is a
  2999. line beginning with `@chapter', `@section', or other similar command.)
  3000.    You can write the structuring command line on the line that follows
  3001. immediately after an `@node' line or else on the line that follows
  3002. after a single `@comment' line or a single `@ifinfo' line.  You cannot
  3003. interpose more than one line between the `@node' line and the
  3004. structuring command line; and you may interpose only an `@comment' line
  3005. or an `@ifinfo' line.
  3006.    Commands which work on a whole buffer require that the `Top' node be
  3007. followed by a node with an `@chapter' or equivalent-level command.
  3008. Note that the menu updating commands will not create a main or master
  3009. menu for a Texinfo file that has only `@chapter'-level nodes!  The menu
  3010. updating commands only create menus *within* nodes for lower level
  3011. nodes.  To create a menu of chapters, you must provide a `Top' node.
  3012.    The menu updating commands remove menu entries that refer to other
  3013. Info files since they do not refer to nodes within the current buffer.
  3014. This is a deficiency.  Rather than use menu entries, you can use cross
  3015. references to refer to other Info files.  None of the updating commands
  3016. affect cross references.
  3017.    Texinfo mode has five updating commands that are used most often: two
  3018. are for updating the node pointers or menu of a single node (or a
  3019. region); two are for updating every node pointer and menu in a file;
  3020. and one, the `texinfo-master-menu' command, is for creating a master
  3021. menu for a complete file, and optionally, for updating every node and
  3022. menu in the whole Texinfo file.
  3023.    The `texinfo-master-menu' command is the primary command:
  3024. `C-c C-u m'
  3025. `M-x texinfo-master-menu'
  3026.      Create or update a master menu that includes all the other menus
  3027.      (incorporating the descriptions from pre-existing menus, if any).
  3028.      With an argument (prefix argument, `C-u,' if interactive), first
  3029.      create or update all the nodes and all the regular menus in the
  3030.      buffer before constructing the master menu.  (*Note The Top Node
  3031.      and Master Menu: The Top Node, for more about a master menu.)
  3032.      For `texinfo-master-menu' to work, the Texinfo file must have a
  3033.      `Top' node and at least one subsequent node.
  3034.      After extensively editing a Texinfo file, you can type the
  3035.      following:
  3036.           C-u M-x texinfo-master-menu
  3037.      or
  3038.           C-u C-c C-u m
  3039.      This updates all the nodes and menus completely and all at once.
  3040.    The other major updating commands do smaller jobs and are designed
  3041. for the person  who updates nodes and menus as he or she writes a
  3042. Texinfo file.
  3043.    The commands are:
  3044. `C-c C-u C-n'
  3045. `M-x texinfo-update-node'
  3046.      Insert the `Next', `Previous', and `Up' pointers for the node that
  3047.      point is within (i.e., for the `@node' line preceding point).  If
  3048.      the `@node' line has pre-existing `Next', `Previous', or `Up'
  3049.      pointers in it, the old pointers are removed and new ones inserted.
  3050.      With an argument (prefix argument, `C-u', if interactive), this
  3051.      command updates all `@node' lines in the region (which is the text
  3052.      between point and mark).
  3053. `C-c C-u C-m'
  3054. `M-x texinfo-make-menu'
  3055.      Create or update the menu in the node that point is within.  With
  3056.      an argument (`C-u' as prefix argument, if interactive), the
  3057.      command makes or updates menus for the nodes which are either
  3058.      within or a part of the region.
  3059.      Whenever `texinfo-make-menu' updates an existing menu, the
  3060.      descriptions from that menu are incorporated into the new menu.
  3061.      This is done by copying descriptions from the existing menu to the
  3062.      entries in the new menu that have the same node names.  If the
  3063.      node names are different, the descriptions are not copied to the
  3064.      new menu.
  3065. `C-c C-u C-e'
  3066. `M-x texinfo-every-node-update'
  3067.      Insert or update the `Next', `Previous', and `Up' pointers for
  3068.      every node in the buffer.
  3069. `C-c C-u C-a'
  3070. `M-x texinfo-all-menus-update'
  3071.      Create or update all the menus in the buffer.  With an argument
  3072.      (`C-u' as prefix argument, if interactive), first insert or update
  3073.      all the node pointers before working on the menus.
  3074.      If a master menu exists, the `texinfo-all-menus-update' command
  3075.      updates it; but the command does not create a new master menu if
  3076.      none already exists.  (Use the `texinfo-master-menu' command for
  3077.      that.)
  3078.      When working on a document that does not merit a master menu, you
  3079.      can type the following:
  3080.           C-u C-c C-u C-a
  3081.      or
  3082.           C-u M-x texinfo-all-menus-update
  3083.      This updates all the nodes and menus.
  3084.    The `texinfo-column-for-description' variable specifies the column
  3085. to which menu descriptions are indented.  By default, the value is 32
  3086. although it is often useful to reduce it to as low as 24.  You can set
  3087. the variable with the `M-x edit-options' command (*note Editing
  3088. Variable Values: (emacs)Edit Options.) or with the `M-x set-variable'
  3089. command (*note Examining and Setting Variables: (emacs)Examining.).
  3090.    Also, the `texinfo-indent-menu-description' command may be used to
  3091. indent existing menu descriptions to a specified column.  Finally, if
  3092. you wish, you can use the `texinfo-insert-node-lines' command to insert
  3093. missing `@node' lines into a file.  (*Note Other Updating Commands::,
  3094. for more information.)
  3095. File: texi.info,  Node: Updating Requirements,  Next: Other Updating Commands,  Prev: Updating Commands,  Up: Updating Nodes and Menus
  3096. Updating Requirements
  3097. ---------------------
  3098.    To use the updating commands, you must organize the Texinfo file
  3099. hierarchically with chapters, sections, subsections, and the like.
  3100. When you construct the hierarchy of the manual, do not `jump down' more
  3101. than one level at a time: you can follow the `Top' node with a chapter,
  3102. but not with a section; you can follow a chapter with a section, but
  3103. not with a subsection.  However, you may `jump up' any number of levels
  3104. at one time--for example, from a subsection to a chapter.
  3105.    Each `@node' line, with the exception of the line for the `Top'
  3106. node, must be followed by a line with a structuring command such as
  3107. `@chapter', `@section', or `@unnumberedsubsec'.
  3108.    Each `@node' line/structuring-command line combination must look
  3109. either like this:
  3110.      @node     Comments,  Minimum, Conventions, Overview
  3111.      @comment  node-name, next,    previous,    up
  3112.      @section Comments
  3113.    or like this (without the `@comment' line):
  3114.      @node Comments, Minimum, Conventions, Overview
  3115.      @section Comments
  3116. In this example, `Comments' is the name of both the node and the
  3117. section.  The next node is called `Minimum' and the previous node is
  3118. called `Conventions'.  The `Comments' section is within the `Overview'
  3119. node, which is specified by the `Up' pointer.  (Instead of an
  3120. `@comment' line, you can write an `@ifinfo' line.)
  3121.    If a file has a `Top' node, it must be called `top' or `Top' and be
  3122. the first node in the file.
  3123.    The menu updating commands create a menu of sections within a
  3124. chapter, a menu of subsections within a section, and so on.  This means
  3125. that you must have a `Top' node if you want a menu of chapters.
  3126.    Incidentally, the `makeinfo' command will create an Info file for a
  3127. hierarchically organized Texinfo file that lacks `Next', `Previous' and
  3128. `Up' pointers.  Thus, if you can be sure that your Texinfo file will be
  3129. formatted with `makeinfo', you have no need for the `update node'
  3130. commands.  (*Note Creating an Info File: Create an Info File, for more
  3131. information about `makeinfo'.)  However, both `makeinfo' and the
  3132. `texinfo-format-...' commands require that you insert menus in the file.
  3133. File: texi.info,  Node: Other Updating Commands,  Prev: Updating Requirements,  Up: Updating Nodes and Menus
  3134. Other Updating Commands
  3135. -----------------------
  3136.    In addition to the five major updating commands, Texinfo mode
  3137. possesses several less frequently used updating commands:
  3138. `M-x texinfo-insert-node-lines'
  3139.      Insert `@node' lines before the `@chapter', `@section', and other
  3140.      sectioning commands wherever they are missing throughout a region
  3141.      in a Texinfo file.
  3142.      With an argument (`C-u' as prefix argument, if interactive), the
  3143.      `texinfo-insert-node-lines' command not only inserts `@node' lines
  3144.      but also inserts the chapter or section titles as the names of the
  3145.      corresponding nodes.  In addition, it inserts the titles as node
  3146.      names in pre-existing `@node' lines that lack names.  Since node
  3147.      names should be more concise than section or chapter titles, you
  3148.      must manually edit node names so inserted.
  3149.      For example, the following marks a whole buffer as a region and
  3150.      inserts `@node' lines and titles throughout:
  3151.           C-x h C-u M-x texinfo-insert-node-lines
  3152.      (Note that this command inserts titles as node names in `@node'
  3153.      lines; the `texinfo-start-menu-description' command (*note
  3154.      Inserting Frequently Used Commands: Inserting.) inserts titles as
  3155.      descriptions in menu entries, a different action.  However, in both
  3156.      cases, you need to edit the inserted text.)
  3157. `M-x texinfo-multiple-files-update'
  3158.      Update nodes and menus in a document built from several separate
  3159.      files.  With `C-u' as a prefix argument, create and insert a
  3160.      master menu in the outer file.  With a numeric prefix argument,
  3161.      such as `C-u 2', first update all the menus and all the `Next',
  3162.      `Previous', and `Up' pointers of all the included files before
  3163.      creating and inserting a master menu in the outer file.  The
  3164.      `texinfo-multiple-files-update' command is described in the
  3165.      appendix on `@include' files.  *Note
  3166.      texinfo-multiple-files-update::.
  3167. `M-x texinfo-indent-menu-description'
  3168.      Indent every description in the menu following point to the
  3169.      specified column.  You can use this command to give yourself more
  3170.      space for descriptions.  With an argument (`C-u' as prefix
  3171.      argument, if interactive), the `texinfo-indent-menu-description'
  3172.      command indents every description in every menu in the region.
  3173.      However, this command does not indent the second and subsequent
  3174.      lines of a multi-line description.
  3175. `M-x texinfo-sequential-node-update'
  3176.      Insert the names of the nodes immediately following and preceding
  3177.      the current node as the `Next' or `Previous' pointers regardless
  3178.      of those nodes' hierarchical level.  This means that the `Next'
  3179.      node of a subsection may well be the next chapter.  Sequentially
  3180.      ordered nodes are useful for novels and other documents that you
  3181.      read through sequentially.  (However, in Info, the `g* RET'
  3182.      command lets you look through the file sequentially, so
  3183.      sequentially ordered nodes are not strictly necessary.)  With an
  3184.      argument (prefix argument, if interactive), the
  3185.      `texinfo-sequential-node-update' command sequentially updates all
  3186.      the nodes in the region.
  3187. File: texi.info,  Node: Info Formatting,  Next: Printing,  Prev: Updating Nodes and Menus,  Up: Texinfo Mode
  3188. Formatting for Info
  3189. ===================
  3190.    Texinfo mode provides several commands for formatting part or all of
  3191. a Texinfo file for Info.  Often, when you are writing a document, you
  3192. want to format only part of a file--that is, a region.
  3193.    You can use either the `texinfo-format-region' or the
  3194. `makeinfo-region' command to format a region:
  3195. `C-c C-e C-r'
  3196. `M-x texinfo-format-region'
  3197. `C-c C-m C-r'
  3198. `M-x makeinfo-region'
  3199.      Format the current region for Info.
  3200.    You can use either the `texinfo-format-buffer' or the
  3201. `makeinfo-buffer' command to format a whole buffer:
  3202. `C-c C-e C-b'
  3203. `M-x texinfo-format-buffer'
  3204. `C-c C-m C-b'
  3205. `M-x makeinfo-buffer'
  3206.      Format the current buffer for Info.
  3207.    For example, after writing a Texinfo file, you can type the
  3208. following:
  3209.      C-u C-c C-u m
  3210.      C-u M-x texinfo-master-menu
  3211. This updates all the nodes and menus.  Then type the following to create
  3212. an Info file:
  3213.      C-c C-m C-b
  3214.      M-x makeinfo-buffer
  3215.    For the Info formatting commands to work, the file *must* include a
  3216. line that has `@setfilename' in its header.
  3217.    Not all systems support the `makeinfo'-based formatting commands.
  3218.    *Note Create an Info File::, for details about Info formatting.
  3219. File: texi.info,  Node: Printing,  Next: Texinfo Mode Summary,  Prev: Info Formatting,  Up: Texinfo Mode
  3220. Formatting and Printing
  3221. =======================
  3222.    Typesetting and printing a Texinfo file is a multi-step process in
  3223. which you first create a file for printing (called a DVI file), and then
  3224. print the file.  Optionally, you may also create indices.  To do this,
  3225. you must run the `texindex' command after first running the `tex'
  3226. typesetting command; and then you must run the `tex' command again.
  3227.    Often, when you are writing a document, you want to typeset and print
  3228. only part of a file to see what it will look like.  You can use the
  3229. `texinfo-tex-region' and related commands for this purpose.  Use the
  3230. `texinfo-tex-buffer' command to format all of a buffer.
  3231. `C-c C-t C-r'
  3232. `M-x texinfo-tex-region'
  3233.      Run TeX on the region.
  3234. `C-c C-t C-b'
  3235. `M-x texinfo-tex-buffer'
  3236.      Run TeX on the buffer.
  3237. `C-c C-t C-i'
  3238. `M-x texinfo-texindex'
  3239.      Run `texindex' to sort the indices of a Texinfo file formatted with
  3240.      `texinfo-tex-region' or `texinfo-tex-buffer'.  You must run the
  3241.      `tex' command a second time after sorting the raw index files.
  3242. `C-c C-t C-p'
  3243. `M-x texinfo-tex-print'
  3244.      Print the file (or the part of the file) previously formatted with
  3245.      `texinfo-tex-buffer' or `texinfo-tex-region'.
  3246.    For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
  3247. *must* start with a `\input texinfo' line and must include an
  3248. `@settitle' line.  The file must end with `@bye' on a line by itself.
  3249. (When you use `texinfo-tex-region', you must surround the `@settitle'
  3250. line with start-of-header and end-of-header lines.)
  3251.    *Note Format/Print Hardcopy::, for a description of the other TeX
  3252. related commands, such as `tex-show-print-queue'.
  3253. File: texi.info,  Node: Texinfo Mode Summary,  Prev: Printing,  Up: Texinfo Mode
  3254. Texinfo Mode Summary
  3255. ====================
  3256.    In Texinfo mode, each set of commands has default keybindings that
  3257. begin with the same keys.  All the commands that are custom-created for
  3258. Texinfo mode begin with `C-c'.  The keys are somewhat mnemonic.
  3259. Insert Commands
  3260. ---------------
  3261.    The insert commands are invoked by typing `C-c' twice and then the
  3262. first letter of the @-command to be inserted.  (It might make more
  3263. sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
  3264. is quick to type.)
  3265.      C-c C-c c       Insert `@code'.
  3266.      C-c C-c d       Insert `@dfn'.
  3267.      C-c C-c e       Insert `@end'.
  3268.      C-c C-c i       Insert `@item'.
  3269.      C-c C-c n       Insert `@node'.
  3270.      C-c C-c s       Insert `@samp'.
  3271.      C-c C-c v       Insert `@var'.
  3272.      C-c C-c {       Insert braces.
  3273.      C-c C-c ]
  3274.      C-c C-c }       Move out of enclosing braces.
  3275.      
  3276.      C-c C-c C-d     Insert a node's section title
  3277.                      in the space for the description
  3278.                      in a menu entry line.
  3279. Show Structure
  3280. --------------
  3281.    The `texinfo-show-structure' command is often used within a narrowed
  3282. region.
  3283.      C-c C-s         List all the headings.
  3284. The Master Update Command
  3285. -------------------------
  3286.    The `texinfo-master-menu' command creates a master menu; and can be
  3287. used to update every node and menu in a file as well.
  3288.      C-c C-u m
  3289.      M-x texinfo-master-menu
  3290.                      Create or update a master menu.
  3291.      
  3292.      C-u C-c C-u m   With `C-u' as a prefix argument, first
  3293.                      create or update all nodes and regular
  3294.                      menus, and then create a master menu.
  3295. Update Pointers
  3296. ---------------
  3297.    The update pointer commands are invoked by typing `C-c C-u' and then
  3298. either typing `C-n' for `texinfo-update-node' or typing `C-e' for
  3299. `texinfo-every-node-update'.
  3300.      C-c C-u C-n     Update a node.
  3301.      C-c C-u C-e     Update every node in the buffer.
  3302. Update Menus
  3303. ------------
  3304.    Invoke the  update menu commands by typing `C-c C-u' and then either
  3305. `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
  3306. To update both nodes and menus at the same time, precede `C-c C-u C-a'
  3307. with `C-u'.
  3308.      C-c C-u C-m     Make or update a menu.
  3309.      
  3310.      C-c C-u C-a     Make or update all
  3311.                      menus in a buffer.
  3312.      
  3313.      C-u C-c C-u C-a With `C-u' as a prefix argument,
  3314.                      first create or update all nodes and
  3315.                      then create or update all menus.
  3316. Format for Info
  3317. ---------------
  3318.    The Info formatting commands that are written in Emacs Lisp are
  3319. invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
  3320. for the whole buffer.
  3321.    The Info formatting commands that are written in C and based on the
  3322. `makeinfo' program are invoked by typing `C-c C-m' and then either
  3323. `C-r' for a region or `C-b' for the whole buffer.
  3324. Use the `texinfo-format...' commands:
  3325.      C-c C-e C-r     Format the region.
  3326.      C-c C-e C-b     Format the buffer.
  3327. Use `makeinfo':
  3328.      C-c C-m C-r     Format the region.
  3329.      C-c C-m C-b     Format the buffer.
  3330.      C-c C-m C-l     Recenter the `makeinfo' output buffer.
  3331.      C-c C-m C-k     Kill the `makeinfo' formatting job.
  3332. Typeset and Print
  3333. -----------------
  3334.    The TeX typesetting and printing commands are invoked by typing `C-c
  3335. C-t' and then another control command: `C-r' for `texinfo-tex-region',
  3336. `C-b' for `texinfo-tex-buffer', and so on.
  3337.      C-c C-t C-r     Run TeX on the region.
  3338.      C-c C-t C-b     Run TeX on the buffer.
  3339.      C-c C-t C-i     Run `texindex'.
  3340.      C-c C-t C-p     Print the DVI file.
  3341.      C-c C-t C-q     Show the print queue.
  3342.      C-c C-t C-d     Delete a job from the print queue.
  3343.      C-c C-t C-k     Kill the current TeX formatting job.
  3344.      C-c C-t C-x     Quit a currently stopped TeX formatting job.
  3345.      C-c C-t C-l     Recenter the output buffer.
  3346. Other Updating Commands
  3347. -----------------------
  3348.    The `other updating commands' do not have standard keybindings
  3349. because they are rarely used.
  3350.      M-x texinfo-insert-node-lines
  3351.                      Insert missing `@node' lines in region.
  3352.                      With `C-u' as a prefix argument,
  3353.                      use section titles as node names.
  3354.      
  3355.      M-x texinfo-multiple-files-update
  3356.                      Update a multi-file document.
  3357.                      With `C-u 2' as a prefix argument,
  3358.                      create or update all nodes and menus
  3359.                      in all included files first.
  3360.      
  3361.      M-x texinfo-indent-menu-description
  3362.                      Indent descriptions.
  3363.      
  3364.      M-x texinfo-sequential-node-update
  3365.                      Insert node pointers in strict sequence.
  3366. File: texi.info,  Node: Beginning a File,  Next: Ending a File,  Prev: Texinfo Mode,  Up: Top
  3367. Beginning a Texinfo File
  3368. ************************
  3369.    Certain pieces of information must be provided at the beginning of a
  3370. Texinfo file, such as the name of the file and the title of the
  3371. document.
  3372. * Menu:
  3373. * Four Parts::                  Four parts begin a Texinfo file.
  3374. * Sample Beginning::            Here is a sample beginning for a Texinfo file.
  3375. * Header::                      The very beginning of a Texinfo file.
  3376. * Info Summary and Permissions::  Summary and copying permissions for Info.
  3377. * Titlepage & Copyright Page::  Creating the title and copyright pages.
  3378. * The Top Node::                Creating the `Top' node and master menu.
  3379. * Software Copying Permissions::  Ensure that you and others continue to
  3380.                                   have the right to use and share software.
  3381. File: texi.info,  Node: Four Parts,  Next: Sample Beginning,  Up: Beginning a File
  3382. Four Parts Begin a File
  3383. =======================
  3384.    Generally, the beginning of a Texinfo file has four parts:
  3385.   1. The header, delimited by special comment lines, that includes the
  3386.      commands for naming the Texinfo file and telling TeX what
  3387.      definitions' file to use when processing the Texinfo file.
  3388.   2. A short statement of what the file is about, with a copyright
  3389.      notice and copying permissions.  This is enclosed in `@ifinfo' and
  3390.      `@end ifinfo' commands so that the formatters place it only in the
  3391.      Info file.
  3392.   3. A title page and copyright page, with a copyright notice and
  3393.      copying permissions.  This is enclosed between `@titlepage' and
  3394.      `@end titlepage' commands.  The title and copyright page appear
  3395.      only in the printed manual.
  3396.   4. The `Top' node that contains a menu for the whole Info file.  The
  3397.      contents of this node appear only in the Info file.
  3398.    Also, optionally, you may include the copying conditions for a
  3399. program and a warranty disclaimer.  The copying section will be
  3400. followed by an introduction or else by the first chapter of the manual.
  3401.    Since the copyright notice and copying permissions for the Texinfo
  3402. document (in contrast to the copying permissions for a program) are in
  3403. parts that appear only in the Info file or only in the printed manual,
  3404. this information must be given twice.
  3405. File: texi.info,  Node: Sample Beginning,  Next: Header,  Prev: Four Parts,  Up: Beginning a File
  3406. Sample Texinfo File Beginning
  3407. =============================
  3408.    The following sample shows what is needed.
  3409.      \input texinfo   @c -*-texinfo-*-
  3410.      @c %**start of header
  3411.      @setfilename NAME-OF-INFO-FILE
  3412.      @settitle NAME-OF-MANUAL
  3413.      @setchapternewpage odd
  3414.      @c %**end of header
  3415.      
  3416.      @ifinfo
  3417.      This file documents ...
  3418.      
  3419.      Copyright YEAR COPYRIGHT-OWNER
  3420.      
  3421.      Permission is granted to ...
  3422.      @end ifinfo
  3423.      
  3424.      @c  This title page illustrates only one of the
  3425.      @c  two methods of forming a title page.
  3426.      
  3427.      @titlepage
  3428.      @title NAME-OF-MANUAL-WHEN-PRINTED
  3429.      @subtitle SUBTITLE-IF-ANY
  3430.      @subtitle SECOND-SUBTITLE
  3431.      @author AUTHOR
  3432.      
  3433.      @c  The following two commands
  3434.      @c  start the copyright page.
  3435.      @page
  3436.      @vskip 0pt plus 1filll
  3437.      Copyright @copyright{} YEAR COPYRIGHT-OWNER
  3438.      
  3439.      Published by ...
  3440.      
  3441.      Permission is granted to ...
  3442.      @end titlepage
  3443.      
  3444.      @node Top, Overview, (dir), (dir)
  3445.      
  3446.      @ifinfo
  3447.      This document describes ...
  3448.      
  3449.      This document applies to version ...
  3450.      of the program named ...
  3451.      @end ifinfo
  3452.      
  3453.      @menu
  3454.      * Copying::          Your rights and freedoms.
  3455.      * First Chapter::    Getting started ...
  3456.      * Second Chapter::              ...
  3457.        ...
  3458.        ...
  3459.      @end menu
  3460.      
  3461.      @node    First Chapter, Second Chapter, top,      top
  3462.      @comment node-name,     next,           previous, up
  3463.      @chapter First Chapter
  3464.      @cindex Index entry for First Chapter
  3465. File: texi.info,  Node: Header,  Next: Info Summary and Permissions,  Prev: Sample Beginning,  Up: Beginning a File
  3466. The Texinfo File Header
  3467. =======================
  3468.    Texinfo files start with at least three lines that provide Info and
  3469. TeX with necessary information.  These are the `\input texinfo' line,
  3470. the `@settitle' line, and the `@setfilename' line.  If you want to run
  3471. TeX on just a part of the Texinfo File, you must write the `@settitle'
  3472. and `@setfilename' lines between start-of-header and end-of-header
  3473. lines.
  3474.    Thus, the beginning of a Texinfo file looks like this:
  3475.      \input texinfo   @c -*-texinfo-*-
  3476.      @setfilename sample.info
  3477.      @settitle Sample Document
  3478. or else like this:
  3479.      \input texinfo   @c -*-texinfo-*-
  3480.      @c %**start of header
  3481.      @setfilename sample.info
  3482.      @settitle Sample Document
  3483.      @c %**end of header
  3484. * Menu:
  3485. * First Line::                  The first line of a Texinfo file.
  3486. * Start of Header::             Formatting a region requires this.
  3487. * setfilename::                 Tell Info the name of the Info file.
  3488. * settitle::                    Create a title for the printed work.
  3489. * setchapternewpage::           Start chapters on right-hand pages.
  3490. * paragraphindent::             An option to specify paragraph indentation.
  3491. * End of Header::               Formatting a region requires this.
  3492. File: texi.info,  Node: First Line,  Next: Start of Header,  Up: Header
  3493. The First Line of a Texinfo File
  3494. --------------------------------
  3495.    Every Texinfo file that is to be the top-level input to TeX must
  3496. begin with a line that looks like this:
  3497.      \input texinfo   @c -*-texinfo-*-
  3498. This line serves two functions:
  3499.   1. When the file is processed by TeX, the `\input texinfo' command
  3500.      tells TeX to load the macros needed for processing a Texinfo file.
  3501.      These are in a file called `texinfo.tex', which is usually located
  3502.      in the `/usr/lib/tex/macros' directory.  TeX uses the backslash,
  3503.      `\', to mark the beginning of a command, just as Texinfo uses `@'.
  3504.      The `texinfo.tex' file causes the switch from `\' to `@'; before
  3505.      the switch occurs, TeX requires `\', which is why it appears at
  3506.      the beginning of the file.
  3507.   2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
  3508.      specification tells Emacs to use Texinfo mode.
  3509. File: texi.info,  Node: Start of Header,  Next: setfilename,  Prev: First Line,  Up: Header
  3510. Start of Header
  3511. ---------------
  3512.    Write a start-of-header line on the second line of a Texinfo file.
  3513. Follow the start-of-header line with `@setfilename' and `@settitle'
  3514. lines and, optionally, with other command lines, such as `@smallbook'
  3515. or `@footnotestyle'; and then by an end-of-header line (*note End of
  3516. Header::.).
  3517.    With these lines, you can format part of a Texinfo file for Info or
  3518. typeset part for printing.
  3519.    A start-of-header line looks like this:
  3520.      @c %**start of header
  3521.    The odd string of characters, `%**', is to ensure that no other
  3522. comment is accidentally taken for a start-of-header line.
  3523. File: texi.info,  Node: setfilename,  Next: settitle,  Prev: Start of Header,  Up: Header
  3524. `@setfilename'
  3525. --------------
  3526.    In order to be made into an Info file, a Texinfo file must contain a
  3527. line that looks like this:
  3528.      @setfilename INFO-FILE-NAME
  3529.    Write the `@setfilename' command at the beginning of a line and
  3530. follow it on the same line by the Info file name.  Do not write
  3531. anything else on the line; anything on the line after the command is
  3532. considered part of the file name, including a comment.
  3533.    The `@setfilename' line specifies the name of the Info file to be
  3534. generated.  This name should be different from the name of the Texinfo
  3535. file.  The convention is to write a name with a `.info' extension, to
  3536. produce an Info file name such as `texinfo.info'.
  3537.    Some operating systems cannot handle long file names.  You can run
  3538. into a problem even when the file name you specify is itself short
  3539. enough.  This occurs because the Info formatters split a long Info file
  3540. into short indirect subfiles, and name them by appending `-1', `-2',
  3541. ..., `-10', `-11', and so on, to the original file name.  (*Note Tag
  3542. Files and Split Files: Tag and Split Files.)  The subfile name
  3543. `texinfo.info-10', for example, is too long for some systems; so the
  3544. Info file name for this document is actually `texinfo' rather than
  3545. `texinfo.info'.
  3546.    The Info formatting commands ignore everything written before the
  3547. `@setfilename' line, which is why the very first line of the file (the
  3548. `\input' line) does not need to be commented out.  The `@setfilename'
  3549. line is ignored when you typeset a printed manual.
  3550. File: texi.info,  Node: settitle,  Next: setchapternewpage,  Prev: setfilename,  Up: Header
  3551. `@settitle'
  3552. -----------
  3553.    In order to be made into a printed manual, a Texinfo file must
  3554. contain a line that looks like this:
  3555.      @settitle TITLE
  3556.    Write the `@settitle' command at the beginning of a line and follow
  3557. it on the same line by the title.  This tells TeX the title to use in a
  3558. header or footer.  Do not write anything else on the line; anything on
  3559. the line after the command is considered part of the title, including a
  3560. comment.
  3561.    Conventionally, TeX formats a Texinfo file for double-sided output
  3562. so as to print the title in the left-hand (even-numbered) page headings
  3563. and the current chapter titles in the right-hand (odd-numbered) page
  3564. headings.  (TeX learns the title of each chapter from each `@chapter'
  3565. command.)  Page footers are not printed.
  3566.    Even if you are printing in a single-sided style, TeX looks for an
  3567. `@settitle' command line, in case you include the manual title in the
  3568. heading.
  3569.    The `@settitle' command should precede everything that generates
  3570. actual output in TeX.
  3571.    Although the title in the `@settitle' command is usually the same as
  3572. the title on the title page, it does not affect the title as it appears
  3573. on the title page.  Thus, the two do not need not match exactly;  and
  3574. the title in the `@settitle' command can be a shortened or expanded
  3575. version of the title as it appears on the title page. (*Note
  3576. `@titlepage': titlepage.)
  3577.    TeX prints page headings only for that text that comes after the
  3578. `@end titlepage' command in the Texinfo file, or that comes after an
  3579. `@headings' command that turns on headings.  (*Note The `@headings'
  3580. Command: headings on off, for more information.)
  3581.    You may, if you wish, create your own, customized headings and
  3582. footings.  *Note Page Headings: Headings, for a detailed discussion of
  3583. this process.
  3584. File: texi.info,  Node: setchapternewpage,  Next: paragraphindent,  Prev: settitle,  Up: Header
  3585. `@setchapternewpage'
  3586. --------------------
  3587.    In a book or a manual, text is usually printed on both sides of the
  3588. paper, chapters start on right-hand pages, and right-hand pages have
  3589. odd numbers.  But in short reports, text often is printed only on one
  3590. side of the paper.  Also in short reports, chapters sometimes do not
  3591. start on new pages, but are printed on the same page as the end of the
  3592. preceding chapter, after a small amount of vertical whitespace.
  3593.    You can use the `@setchapternewpage' command with various arguments
  3594. to specify how TeX should start chapters and whether it should typeset
  3595. pages for printing on one or both sides of the paper (single-sided or
  3596. double-sided printing).
  3597.    Write the `@setchapternewpage' command at the beginning of a line
  3598. followed by its argument.
  3599.    For example, you would write the following to cause each chapter to
  3600. start on a fresh odd-numbered page:
  3601.      @setchapternewpage odd
  3602.    You can specify one of three alternatives with the
  3603. `@setchapternewpage' command:
  3604. `@setchapternewpage off'
  3605.      Cause TeX to typeset a new chapter on the same page as the last
  3606.      chapter, after skipping some vertical whitespace.  Also, cause TeX
  3607.      to format page headers for single-sided printing. (You can
  3608.      override the headers format with the `@headings double' command;
  3609.      see *Note The `@headings' Command: headings on off.)
  3610. `@setchapternewpage on'
  3611.      Cause TeX to start new chapters on new pages and to typeset page
  3612.      headers for single-sided printing.  This is the form most often
  3613.      used for short reports.
  3614.      This alternative is the default.
  3615. `@setchapternewpage odd'
  3616.      Cause TeX to start new chapters on new, odd-numbered pages
  3617.      (right-handed pages) and to typeset for double-sided printing.
  3618.      This is the form most often used for books and manuals.
  3619. Texinfo does not have an `@setchapternewpage even' command.
  3620. (You can countermand or modify an `@setchapternewpage' command with an
  3621. `@headings' command.  *Note The `@headings' Command: headings on off.)
  3622.    At the beginning of a manual or book, pages are not numbered--for
  3623. example, the title and copyright pages of a book are not numbered.  By
  3624. convention, table of contents pages are numbered with roman numerals
  3625. and not in sequence with the rest of the document.
  3626.    Since an Info file does not have pages, the `@setchapternewpage'
  3627. command has no effect on it.
  3628.    Usually, you do not write an `@setchapternewpage' command for
  3629. single-sided printing, but accept the default which is to typeset for
  3630. single-sided printing and to start new chapters on new pages.  Usually,
  3631. you write an `@setchapternewpage odd' command for double-sided printing.
  3632. File: texi.info,  Node: paragraphindent,  Next: End of Header,  Prev: setchapternewpage,  Up: Header
  3633. Paragraph Indenting
  3634. -------------------
  3635.    The Info formatting commands may insert spaces at the beginning of
  3636. the first line of each paragraph, thereby indenting that paragraph.  You
  3637. can use the `@paragraphindent' command to specify the indentation.
  3638. Write an `@paragraphindent' command at the beginning of a line followed
  3639. by either `asis' or a number.  The template is:
  3640.      @paragraphindent INDENT
  3641.    The Info formatting commands indent according to the value of INDENT:
  3642.    * If the value of INDENT is `asis', the Info formatting commands do
  3643.      not change the existing indentation.
  3644.    * If the value of INDENT is 0, the Info formatting commands delete
  3645.      existing indentation.
  3646.    * If the value of INDENT is greater than 0, the Info formatting
  3647.      commands indent the paragraph by that number of spaces.
  3648.    The default value of INDENT is `asis'.
  3649.    Write the `@paragraphindent' command before or shortly after the
  3650. end-of-header line at the beginning of a Texinfo file.  (If you write
  3651. the command between the start-of-header and end-of-header lines, the
  3652. region formatting commands indent paragraphs as specified.)
  3653.    A peculiarity of `texinfo-format-buffer' and `texinfo-format-region'
  3654. is that they do not indent (nor fill) paragraphs that contain `@w' or
  3655. `@*' commands.  *Note Refilling Paragraphs::, for a detailed
  3656. description of what goes on.
  3657. File: texi.info,  Node: End of Header,  Prev: paragraphindent,  Up: Header
  3658. End of Header
  3659. -------------
  3660.    Follow the header lines with an end-of-header line.  An
  3661. end-of-header line looks like this:
  3662.      @c %**end of header
  3663.    If you include the `@setchapternewpage' command between the
  3664. start-of-header and end-of-header lines, TeX will typeset a region as
  3665. that command specifies.  Similarly, if you include an `@smallbook'
  3666. command between the start-of-header and end-of-header lines, TeX will
  3667. typeset a region in the "small" book format.
  3668.    The reason for the odd string of characters (`%**') is so that the
  3669. `texinfo-tex-region' command does not accidentally find something that
  3670. it should not when it is looking for the header.
  3671.    The start-of-header line and the end-of-header line are Texinfo mode
  3672. variables that you can change.
  3673. File: texi.info,  Node: Info Summary and Permissions,  Next: Titlepage & Copyright Page,  Prev: Header,  Up: Beginning a File
  3674. Summary and Copying Permissions for Info
  3675. ========================================
  3676.    The title page and the copyright page appear only in the printed
  3677. copy of the manual; therefore, the same information must be inserted in
  3678. a section that appears only in the Info file.  This section usually
  3679. contains a brief description of the contents of the Info file, a
  3680. copyright notice, and copying permissions.
  3681.    The copyright notice should read:
  3682.      Copyright YEAR COPYRIGHT-OWNER
  3683. and be put on a line by itself.
  3684.    Standard text for the copyright permissions is contained in an
  3685. appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
  3686. Permissions, for the complete text.
  3687.    The permissions text appears in an Info file *before* the first
  3688. node.  This mean that a reader does *not* see this text when reading
  3689. the file using Info, except when using the advanced Info command `g *'.
  3690. File: texi.info,  Node: Titlepage & Copyright Page,  Next: The Top Node,  Prev: Info Summary and Permissions,  Up: Beginning a File
  3691. The Title and Copyright Pages
  3692. =============================
  3693.    A manual's name and author are usually printed on a title page.
  3694. Sometimes copyright information is printed on the title page as well;
  3695. more often, copyright information is printed on the back of the title
  3696. page.
  3697.    The title and copyright pages appear in the printed manual, but not
  3698. in the Info file.  Because of this, it is possible to use several
  3699. slightly obscure TeX typesetting commands that cannot be used in an
  3700. Info file.  In addition, this part of the beginning of a Texinfo file
  3701. contains the text of the copying permissions that will appear in the
  3702. printed manual.
  3703.    *Note Titlepage Copying Permissions: Titlepage Permissions, for the
  3704. standard text for the copyright permissions.
  3705. * Menu:
  3706. * titlepage::                   Create a title for the printed document.
  3707. * titlefont center sp::         The `@titlefont', `@center',
  3708.                                   and `@sp' commands.
  3709. * title subtitle author::       The `@title', `@subtitle',
  3710.                                   and `@author' commands.
  3711. * Copyright & Permissions::     How to write the copyright notice and
  3712.                                   include copying permissions.
  3713. * end titlepage::               Turn on page headings after the title and
  3714.                                   copyright pages.
  3715. * headings on off::             An option for turning headings on and off
  3716.                                   and double or single sided printing.
  3717. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  3718. file texi.texi.
  3719.    This file documents Texinfo, a documentation system that uses a
  3720. single source file to produce both on-line information and a printed
  3721. manual.
  3722.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  3723.    This is the second edition of the Texinfo documentation,
  3724. and is consistent with version 2 of `texinfo.tex'.
  3725.    Permission is granted to make and distribute verbatim copies of this
  3726. manual provided the copyright notice and this permission notice are
  3727. preserved on all copies.
  3728.    Permission is granted to copy and distribute modified versions of
  3729. this manual under the conditions for verbatim copying, provided that
  3730. the entire resulting derived work is distributed under the terms of a
  3731. permission notice identical to this one.
  3732.    Permission is granted to copy and distribute translations of this
  3733. manual into another language, under the above conditions for modified
  3734. versions, except that this permission notice may be stated in a
  3735. translation approved by the Free Software Foundation.
  3736. File: texi.info,  Node: titlepage,  Next: titlefont center sp,  Up: Titlepage & Copyright Page
  3737. `@titlepage'
  3738. ------------
  3739.    Start the material for the title page and following copyright page
  3740. with `@titlepage' on a line by itself and end it with `@end titlepage'
  3741. on a line by itself.
  3742.    The `@end titlepage' command starts a new page and turns on page
  3743. numbering. (*Note Page Headings: Headings, for details about how to
  3744. generate of page headings.)  All the material that you want to appear
  3745. on unnumbered pages should be put between the `@titlepage' and `@end
  3746. titlepage' commands.  By using the `@page' command you can force a page
  3747. break within the region delineated by the `@titlepage' and `@end
  3748. titlepage' commands and thereby create more than one unnumbered page.
  3749. This is how the copyright page is produced.  (The `@titlepage' command
  3750. might perhaps have been better named the `@titleandadditionalpages'
  3751. command, but that would have been rather long!)
  3752.    When you write a manual about a computer program, you should write
  3753. the version of the program to which the manual applies on the title
  3754. page.  If the manual changes more frequently than the program or is
  3755. independent of it, you should also include an edition number(1) for the
  3756. manual.  This helps readers keep track of which manual is for which
  3757. version of the program.  (The `Top' node should also contain this
  3758. information; see *Note `@top': makeinfo top.)
  3759.    Texinfo provides two methods for creating a title page.  One method
  3760. uses the `@titlefont', `@sp', and `@center' commands to generate a
  3761. title page in which the words on the page are centered.
  3762.    The second method uses the `@title', `@subtitle', and `@author'
  3763. commands to create a title page with black rules under the title and
  3764. author lines and the subtitle text set flush to the right hand side of
  3765. the page.  With this method, you do not specify any of the actual
  3766. formatting of the title page.  You specify the text you want, and
  3767. Texinfo does the formatting.  You may use either method.
  3768.    ---------- Footnotes ----------
  3769.    (1)  We have found that it is helpful to refer to versions of
  3770. manuals as `editions' and versions of programs as `versions';
  3771. otherwise, we find we are liable to confuse each other in conversation
  3772. by referring to both the documentation and the software with the same
  3773. words.
  3774. File: texi.info,  Node: titlefont center sp,  Next: title subtitle author,  Prev: titlepage,  Up: Titlepage & Copyright Page
  3775. `@titlefont', `@center', and `@sp'
  3776. ----------------------------------
  3777.    You can use the `@titlefont', `@sp', and `@center' commands to
  3778. create a title page for a printed document.  (This is the first of the
  3779. two methods for creating a title page in Texinfo.)
  3780.    Use the `@titlefont' command to select a large font suitable for the
  3781. title itself.
  3782.    For example:
  3783.      @titlefont{Texinfo}
  3784.    Use the `@center' command at the beginning of a line to center the
  3785. remaining text on that line.  Thus,
  3786.      @center @titlefont{Texinfo}
  3787. centers the title, which in this example is "Texinfo" printed in the
  3788. title font.
  3789.    Use the `@sp' command to insert vertical space.  For example:
  3790.      @sp 2
  3791. This inserts two blank lines on the printed page.  (*Note `@sp': sp,
  3792. for more information about the `@sp' command.)
  3793.    A template for this method looks like this:
  3794.      @titlepage
  3795.      @sp 10
  3796.      @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
  3797.      @sp 2
  3798.      @center SUBTITLE-IF-ANY
  3799.      @sp 2
  3800.      @center AUTHOR
  3801.      ...
  3802.      @end titlepage
  3803.    The spacing of the example fits an 8 1/2 by 11 inch manual.
  3804. File: texi.info,  Node: title subtitle author,  Next: Copyright & Permissions,  Prev: titlefont center sp,  Up: Titlepage & Copyright Page
  3805. `@title', `@subtitle', and `@author'
  3806. ------------------------------------
  3807.    You can use the `@title', `@subtitle', and `@author' commands to
  3808. create a title page in which the vertical and horizontal spacing is
  3809. done for you automatically.  This contrasts with the method described in
  3810. the previous section, in which the `@sp' command is needed to adjust
  3811. vertical spacing.
  3812.    Write the `@title', `@subtitle', or `@author' commands at the
  3813. beginning of a line followed by the title, subtitle, or author.
  3814.    The `@title' command produces a line in which the title is set flush
  3815. to the left-hand side of the page in a larger than normal font.  The
  3816. title is underlined with a black rule.
  3817.    The `@subtitle' command sets subtitles in a normal-sized font flush
  3818. to the right-hand side of the page.
  3819.    The `@author' command sets the names of the author or authors in a
  3820. middle-sized font flush to the left-hand side of the page on a line
  3821. near the bottom of the title page.  The names are underlined with a
  3822. black rule that is thinner than the rule that underlines the title.
  3823. (The black rule only occurs if the `@author' command line is followed
  3824. by an `@page' command line.)
  3825.    There are two ways to use the `@author' command: you can write the
  3826. name or names on the remaining part of the line that starts with an
  3827. `@author' command:
  3828.      @author by Jane Smith and John Doe
  3829. or you can write the names one above each other by using two (or more)
  3830. `@author' commands:
  3831.      @author Jane Smith
  3832.      @author John Doe
  3833. (Only the bottom name is underlined with a black rule.)
  3834.    A template for this method looks like this:
  3835.      @titlepage
  3836.      @title NAME-OF-MANUAL-WHEN-PRINTED
  3837.      @subtitle SUBTITLE-IF-ANY
  3838.      @subtitle SECOND-SUBTITLE
  3839.      @author AUTHOR
  3840.      @page
  3841.      ...
  3842.      @end titlepage
  3843. Contrast this form with the form of a title page written using the
  3844. `@sp', `@center', and `@titlefont' commands:
  3845.      @titlepage
  3846.      @sp 10
  3847.      @center @titlefont{Name of Manual When Printed}
  3848.      @sp 2
  3849.      @center Subtitle, If Any
  3850.      @sp 1
  3851.      @center Second subtitle
  3852.      @sp 2
  3853.      @center Author
  3854.      @page
  3855.      ...
  3856.      @end titlepage
  3857. File: texi.info,  Node: Copyright & Permissions,  Next: end titlepage,  Prev: title subtitle author,  Up: Titlepage & Copyright Page
  3858. Copyright Page and Permissions
  3859. ------------------------------
  3860.    By international treaty, the copyright notice for a book should be
  3861. either on the title page or on the back of the title page.  The
  3862. copyright notice should include the year followed by the name of the
  3863. organization or person who owns the copyright.
  3864.    When the copyright notice is on the back of the title page, that page
  3865. is customarily not numbered.  Therefore, in Texinfo, the information on
  3866. the copyright page should be within `@titlepage' and `@end titlepage'
  3867. commands.
  3868.    Use the `@page' command to cause a page break.  To push the
  3869. copyright notice and the other text on the copyright page towards the
  3870. bottom of the page, you can write a somewhat mysterious line after the
  3871. `@page' command that reads like this:
  3872.      @vskip 0pt plus 1filll
  3873. This is a TeX command that is not supported by the Info formatting
  3874. commands.  The `@vskip' command inserts whitespace.  The `0pt plus
  3875. 1filll' means to put in zero points of mandatory whitespace, and as
  3876. much optional whitespace as needed to push the following text to the
  3877. bottom of the page.  Note the use of three `l's in the word `filll';
  3878. this is the correct usage in TeX.
  3879.    In a printed manual, the `@copyright{}' command generates a `c'
  3880. inside a circle.  (In Info, it generates `(C)'.)  The copyright notice
  3881. itself has the following legally defined sequence:
  3882.      Copyright (C) YEAR COPYRIGHT-OWNER
  3883.    It is customary to put information on how to get a manual after the
  3884. copyright notice, followed by the copying permissions for the manual.
  3885.    Note that permissions must be given here as well as in the summary
  3886. segment within `@ifinfo' and `@end ifinfo' that immediately follows the
  3887. header since this text appears only in the printed manual and the
  3888. `ifinfo' text appears only in the Info file.
  3889.    *Note Sample Permissions::, for the standard text.
  3890. File: texi.info,  Node: end titlepage,  Next: headings on off,  Prev: Copyright & Permissions,  Up: Titlepage & Copyright Page
  3891. Heading Generation
  3892. ------------------
  3893.    An `@end titlepage' command on a line by itself not only marks the
  3894. end of the title and copyright pages, but also causes TeX to start
  3895. generating page headings and page numbers.
  3896.    To repeat what is said elsewhere,  Texinfo has two standard page
  3897. heading formats, one for documents which are printed on one side of
  3898. each sheet of paper (single-sided printing), and the other for
  3899. documents which are printed on both sides of each sheet (double-sided
  3900. printing).  (*Note `@setchapternewpage': setchapternewpage.) You can
  3901. specify these formats in different ways:
  3902.    * The conventional way is to write an `@setchapternewpage' command
  3903.      before the title page commands, and then have the `@end titlepage'
  3904.      command start generating page headings in the manner desired.
  3905.      (*Note `@setchapternewpage': setchapternewpage.)
  3906.    * Alternatively, you can use the `@headings' command to prevent page
  3907.      headings from being generated or to start them for either single or
  3908.      double-sided printing.  (Write an `@headings' command immediately
  3909.      after the `@end titlepage' command.  *Note The `@headings'
  3910.      Command: headings on off, for more information.)
  3911.    * Or, you may specify your own page heading and footing format.
  3912.      *Note Page Headings: Headings, for detailed information about page
  3913.      headings and footings.
  3914.    Most documents are formatted with the standard single-sided or
  3915. double-sided format, using `@setchapternewpage odd' for double-sided
  3916. printing and no `@setchapternewpage' command for single-sided printing.
  3917. File: texi.info,  Node: headings on off,  Prev: end titlepage,  Up: Titlepage & Copyright Page
  3918. The `@headings' Command
  3919. -----------------------
  3920.    The `@headings' command is rarely used.  It specifies what kind of
  3921. page headings and footings to print on each page.  Usually, this is
  3922. controlled by the `@setchapternewpage' command.  You need the
  3923. `@headings' command only if the `@setchapternewpage' command does not
  3924. do what you want, or if you want to turn off pre-defined page headings
  3925. prior to defining your own.  Write an `@headings' command immediately
  3926. after the `@end titlepage' command.
  3927.    There are four ways to use the `@headings' command:
  3928. `@headings off'
  3929.      Turn off printing of page headings.
  3930. `@headings single'
  3931.      Turn on page headings appropriate for single-sided printing.
  3932. `@headings double'
  3933. `@headings on'
  3934.      Turn on page headings appropriate for double-sided printing.  The
  3935.      two commands, `@headings on' and `@headings double', are
  3936.      synonymous.
  3937.    For example, suppose you write `@setchapternewpage off' before the
  3938. `@titlepage' command to tell TeX to start a new chapter on the same
  3939. page as the end of the last chapter.  This command also causes TeX to
  3940. typeset page headers for single-sided printing.  To cause TeX to
  3941. typeset for double sided printing, write `@headings double' after the
  3942. `@end titlepage' command.
  3943.    You can stop TeX from generating any page headings at all by writing
  3944. `@headings off' on a line of its own immediately after the line
  3945. containing the `@end titlepage' command, like this:
  3946.      @end titlepage
  3947.      @headings off
  3948. The `@headings off' command overrides the `@end titlepage' command,
  3949. which would otherwise cause TeX to print page headings.
  3950.    You can also specify your own style of page heading and footing.
  3951. *Note Page Headings: Headings, for more information.
  3952. File: texi.info,  Node: The Top Node,  Next: Software Copying Permissions,  Prev: Titlepage & Copyright Page,  Up: Beginning a File
  3953. The `Top' Node and Master Menu
  3954. ==============================
  3955.    The `Top' node is the node from which you enter an Info file.
  3956.    A `Top' node should contain a brief description of the Info file and
  3957. an extensive, master menu for the whole Info file.  This helps the
  3958. reader understand what the Info file is about.  Also, you should write
  3959. the version number of the program to which the Info file applies; or,
  3960. at least, the edition number.
  3961.    The contents of the `Top' node should appear only in the Info file;
  3962. none of it should appear in printed output, so enclose it between
  3963. `@ifinfo' and `@end ifinfo' commands.  (TeX does not print either an
  3964. `@node' line or a menu; they appear only in Info; strictly speaking,
  3965. you are not required to enclose these parts between `@ifinfo' and `@end
  3966. ifinfo', but it is simplest to do so.  *Note Conditionally Visible
  3967. Text: Conditionals.)
  3968. * Menu:
  3969. * Title of Top Node::           Sketch what the file is about.
  3970. * Master Menu Parts::           A master menu has three or more parts.
  3971. File: texi.info,  Node: Title of Top Node,  Next: Master Menu Parts,  Up: The Top Node
  3972. `Top' Node Title
  3973. ----------------
  3974.    Sometimes, you will want to place an `@top' sectioning command line
  3975. containing the title of the document immediately after the `@node Top'
  3976. line (*note The `@top' Sectioning Command: makeinfo top command., for
  3977. more information).
  3978.    For example, the beginning of the Top node of this manual contains an
  3979. `@top' sectioning command, a short description, and edition and version
  3980. information.  It looks like this:
  3981.      ...
  3982.      @end titlepage
  3983.      
  3984.      @ifinfo
  3985.      @node Top, Copying, (dir), (dir)
  3986.      @top Texinfo
  3987.      
  3988.      Texinfo is a documentation system...
  3989.      
  3990.      This is edition...
  3991.      ...
  3992.      @end ifinfo
  3993.      
  3994.      @menu
  3995.      * Copying::                 Texinfo is freely
  3996.                                    redistributable.
  3997.      * Overview::                What is Texinfo?
  3998.      ...
  3999.      @end menu
  4000.    In a `Top' node, the `Previous', and `Up' nodes usually refer to the
  4001. top level directory of the whole Info system, which is called `(dir)'.
  4002. The `Next' node refers to the first node that follows the main or master
  4003. menu, which is usually the copying permissions, introduction, or first
  4004. chapter.
  4005. File: texi.info,  Node: Master Menu Parts,  Prev: Title of Top Node,  Up: The Top Node
  4006. Parts of a Master Menu
  4007. ----------------------
  4008.    A "master menu" is a detailed main menu listing all the nodes in a
  4009. file.
  4010.    A master menu is enclosed in `@menu' and `@end menu' commands and
  4011. does not appear in the printed document.
  4012.    Generally, a master menu is divided into parts.
  4013.    * The first part contains the major nodes in the Texinfo file: the
  4014.      nodes for the chapters, chapter-like sections, and the appendices.
  4015.    * The second part contains nodes for the indices.
  4016.    * The third and subsequent parts contain a listing of the other,
  4017.      lower level nodes, often ordered by chapter.  This way, rather
  4018.      than go through an intermediary menu, an inquirer can go directly
  4019.      to a particular node when searching for specific information.
  4020.      These menu items are not required; add them if you think they are a
  4021.      convenience.
  4022.    Each section in the menu can be introduced by a descriptive line.  So
  4023. long as the line does not begin with an asterisk, it will not be
  4024. treated as a menu entry.  (*Note Writing a Menu::, for more
  4025. information.)
  4026.    For example, the master menu for this manual looks like the following
  4027. (but has many more entries):
  4028.      @menu
  4029.      * Copying::             Texinfo is freely
  4030.                                redistributable.
  4031.      * Overview::            What is Texinfo?
  4032.      * Texinfo Mode::        Special features in GNU Emacs.
  4033.      ...
  4034.      ...
  4035.      * Command and Variable Index::
  4036.                              An entry for each @-command.
  4037.      * Concept Index::       An entry for each concept.
  4038.      
  4039.       --- The Detailed Node Listing ---
  4040.      
  4041.      Overview of Texinfo
  4042.      
  4043.      * Info Files::          What is an Info file?
  4044.      * Printed Manuals::     Characteristics of
  4045.                                a printed manual.
  4046.      ...
  4047.      ...
  4048.      
  4049.      Using Texinfo Mode
  4050.      
  4051.      * Info on a Region::    Formatting part of a file
  4052.                                for Info.
  4053.      ...
  4054.      ...
  4055.      @end menu
  4056. File: texi.info,  Node: Software Copying Permissions,  Prev: The Top Node,  Up: Beginning a File
  4057. Software Copying Permissions
  4058. ============================
  4059.    If the Texinfo file has a section containing the "General Public
  4060. License" and the distribution information and a warranty disclaimer for
  4061. the software that is documented, this section usually follows the `Top'
  4062. node.  The General Public License is very important to Project GNU
  4063. software.  It ensures that you and others will continue to have a right
  4064. to use and share the software.
  4065.    The copying and distribution information and the disclaimer are
  4066. followed by an introduction or else by the first chapter of the manual.
  4067.    Although an introduction is not a required part of a Texinfo file, it
  4068. is very helpful.  Ideally, it should state clearly and concisely what
  4069. the file is about and who would be interested in reading it.  In
  4070. general, an introduction would follow the licensing and distribution
  4071. information, although sometimes people put it earlier in the document.
  4072. Usually, an introduction is put in an `@unnumbered' section.  (*Note
  4073. The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
  4074. File: texi.info,  Node: Ending a File,  Next: Structuring,  Prev: Beginning a File,  Up: Top
  4075. Ending a Texinfo File
  4076. *********************
  4077.    The end of a Texinfo file should include the commands that create
  4078. indices and generate detailed and summary tables of contents.  And it
  4079. must include the `@bye' command that marks the last line processed by
  4080.    For example:
  4081.      @node    Concept Index,     , Variables Index, Top
  4082.      @c        node-name,    next, previous,        up
  4083.      @unnumbered Concept Index
  4084.      
  4085.      @printindex cp
  4086.      
  4087.      @contents
  4088.      @bye
  4089. * Menu:
  4090. * Printing Indices & Menus::    How to print an index in hardcopy and
  4091.                                   generate index menus in Info.
  4092. * Contents::                    How to create a table of contents.
  4093. * File End::                    How to mark the end of a file.
  4094. File: texi.info,  Node: Printing Indices & Menus,  Next: Contents,  Up: Ending a File
  4095. Index Menus and Printing an Index
  4096. =================================
  4097.    To print an index means to include it as part of a manual or Info
  4098. file.  This does not happen automatically just because you use
  4099. `@cindex' or other index-entry generating commands in the Texinfo file;
  4100. those just cause the raw data for the index to be accumulated.  To
  4101. generate an index, you must include the `@printindex' command at the
  4102. place in the document where you want the index to appear.  Also, as
  4103. part of the process of creating a printed manual, you must run a
  4104. program called `texindex' (*note Format/Print Hardcopy::.) to sort the
  4105. raw data to produce a sorted index file.  The sorted index file is what
  4106. is actually used to print the index.
  4107.    Texinfo offers six different types of predefined index: the concept
  4108. index, the function index, the variables index, the keystroke index, the
  4109. program index, and the data type index (*note Predefined Indices::.).
  4110. Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
  4111. and `tp'.  You may merge indices, or put them into separate sections
  4112. (*note Combining Indices::.); or you may define your own indices (*note
  4113. Defining New Indices: New Indices.).
  4114.    The `@printindex' command takes a two-letter index name, reads the
  4115. corresponding sorted index file and formats it appropriately into an
  4116. index.
  4117.    The `@printindex' command does not generate a chapter heading for
  4118. the index.  Consequently, you should precede the `@printindex' command
  4119. with a suitable section or chapter command (usually `@unnumbered') to
  4120. supply the chapter heading and put the index into the table of
  4121. contents.  Precede the `@unnumbered' command with an `@node' line.
  4122.    For example:
  4123.      @node Variable Index, Concept Index, Function Index, Top
  4124.      @comment    node-name,         next,       previous, up
  4125.      @unnumbered Variable Index
  4126.      
  4127.      @printindex vr
  4128.      @node     Concept Index,     , Variable Index, Top
  4129.      @comment      node-name, next,       previous, up
  4130.      @unnumbered Concept Index
  4131.      
  4132.      @printindex cp
  4133.      @summarycontents
  4134.      @contents
  4135.      @bye
  4136. (Readers often prefer that the concept index come last in a book, since
  4137. that makes it easiest to find.)
  4138. File: texi.info,  Node: Contents,  Next: File End,  Prev: Printing Indices & Menus,  Up: Ending a File
  4139. Generating a Table of Contents
  4140. ==============================
  4141.    The `@chapter', `@section', and other structuring commands supply
  4142. the information to make up a table of contents, but they do not cause
  4143. an actual table to appear in the manual.  To do this, you must use the
  4144. `@contents' and `@summarycontents' commands:
  4145. `@contents'
  4146.      Generate a table of contents in a printed manual, including all
  4147.      chapters, sections, subsections, etc., as well as appendices and
  4148.      unnumbered chapters.  (Headings generated by the `@heading' series
  4149.      of commands do not appear in the table of contents.)  The
  4150.      `@contents' command should be written on a line by itself.
  4151. `@shortcontents'
  4152. `@summarycontents'
  4153.      (`@summarycontents' is a synonym for `@shortcontents'; the two
  4154.      commands are exactly the same.)
  4155.      Generate a short or summary table of contents that lists only the
  4156.      chapters (and appendices and unnumbered chapters).  Omit sections,
  4157.      subsections and subsubsections.  Only a long manual needs a short
  4158.      table of contents in addition to the full table of contents.
  4159.      Write the `@shortcontents' command on a line by itself right
  4160.      *before* the `@contents' command.
  4161.    The table of contents commands automatically generate a chapter-like
  4162. heading at the top of the first table of contents page.  Write the table
  4163. of contents commands at the very end of a Texinfo file, just before the
  4164. `@bye' command, following any index sections--anything in the Texinfo
  4165. file after the table of contents commands will be omitted from the
  4166. table of contents.
  4167.    When you print a manual with a table of contents, the table of
  4168. contents are printed last and numbered with roman numerals.  You need
  4169. to place those pages in their proper place, after the title page,
  4170. yourself.  (This is the only collating you need to do for a printed
  4171. manual.  The table of contents is printed last because it is generated
  4172. after the rest of the manual is typeset.)
  4173.    Here is an example of where to write table of contents commands:
  4174.      INDICES...
  4175.      @shortcontents
  4176.      @contents
  4177.      @bye
  4178.    Since an Info file uses menus instead of tables of contents, the Info
  4179. formatting commands ignore the `@contents' and `@shortcontents'
  4180. commands.
  4181. File: texi.info,  Node: File End,  Prev: Contents,  Up: Ending a File
  4182. `@bye' File Ending
  4183. ==================
  4184.    An `@bye' command terminates TeX or Info formatting.  None of the
  4185. formatting commands see any of the file following `@bye'.  The `@bye'
  4186. command should be on a line by itself.
  4187.    If you wish, you may follow the `@bye' line with notes. These notes
  4188. will not be formatted and will not appear in either Info or a printed
  4189. manual; it is as if text after `@bye' were within `@ignore' ... `@end
  4190. ignore'.  Also, you may follow the `@bye' line with a local variables
  4191. list.  *Note Using Local Variables and the Compile Command:
  4192. Compile-Command, for more information.
  4193. File: texi.info,  Node: Structuring,  Next: Nodes,  Prev: Ending a File,  Up: Top
  4194. Chapter Structuring
  4195. *******************
  4196.    The "chapter structuring" commands divide a document into a
  4197. hierarchy of chapters, sections, subsections, and subsubsections.
  4198. These commands generate large headings; they also provide information
  4199. for the table of contents of a printed manual (*note Generating a Table
  4200. of Contents: Contents.).
  4201.    The chapter structuring commands do not create an Info node
  4202. structure, so normally you should put an `@node' command immediately
  4203. before each chapter structuring command (*note Nodes::.).  The only
  4204. time you are likely to use the chapter structuring commands without
  4205. using the node structuring commands is if you are writing a document
  4206. that contains no cross references and will never be transformed into
  4207. Info format.
  4208.    It is unlikely that you will ever write a Texinfo file that is
  4209. intended only as an Info file and not as a printable document.  If you
  4210. do, you might still use chapter structuring commands to create a
  4211. heading at the top of each node--but you don't need to.
  4212. * Menu:
  4213. * Tree Structuring::            A manual is like an upside down tree ...
  4214. * Structuring Command Types::   How to divide a manual into parts.
  4215. * makeinfo top::                The `@top' command, part of the `Top' node.
  4216. * chapter::
  4217. * unnumbered & appendix::
  4218. * majorheading & chapheading::
  4219. * section::
  4220. * unnumberedsec appendixsec heading::
  4221. * subsection::
  4222. * unnumberedsubsec appendixsubsec subheading::
  4223. * subsubsection::               Commands for the lowest level sections.
  4224. File: texi.info,  Node: Tree Structuring,  Next: Structuring Command Types,  Up: Structuring
  4225. Tree Structure of Sections
  4226. ==========================
  4227.    A Texinfo file is usually structured like a book with chapters,
  4228. sections, subsections, and the like.  This structure can be visualized
  4229. as a tree (or rather as an upside-down tree) with the root at the top
  4230. and the levels corresponding to chapters, sections, subsection, and
  4231. subsubsections.
  4232.    Here is a diagram that shows a Texinfo file with three chapters,
  4233. each of which has two sections.
  4234.                                Top
  4235.                                 |
  4236.               -------------------------------------
  4237.              |                  |                  |
  4238.           Chapter 1          Chapter 2          Chapter 3
  4239.              |                  |                  |
  4240.           --------           --------           --------
  4241.          |        |         |        |         |        |
  4242.       Section  Section   Section  Section   Section  Section
  4243.         1.1      1.2       2.1      2.2       3.1      3.2
  4244.    In a Texinfo file that has this structure, the beginning of Chapter 2
  4245. looks like this:
  4246.      @node    Chapter 2,  Chapter 3, Chapter 1, top
  4247.      @chapter Chapter 2
  4248.    The chapter structuring commands are described in the sections that
  4249. follow; the `@node' and `@menu' commands are described in following
  4250. chapters. (*Note Nodes::, and see *Note Menus::.)
  4251. File: texi.info,  Node: Structuring Command Types,  Next: makeinfo top,  Prev: Tree Structuring,  Up: Structuring
  4252. Types of Structuring Command
  4253. ============================
  4254.    The chapter structuring commands fall into four groups or series,
  4255. each of which contains structuring commands corresponding to the
  4256. hierarchical levels of chapters, sections, subsections, and
  4257. subsubsections.
  4258.    The four groups are the `@chapter' series, the `@unnumbered' series,
  4259. the `@appendix' series, and the `@heading' series.
  4260.    Each command produces titles that have a different appearance on the
  4261. printed page or Info file; only some of the commands produce titles
  4262. that are listed in the table of contents of a printed book or manual.
  4263.    * The `@chapter' and `@appendix' series of commands produce numbered
  4264.      or lettered entries both in the body of a printed work and in its
  4265.      table of contents.
  4266.    * The `@unnumbered' series of commands produce unnumbered entries
  4267.      both in the body of a printed work and in its table of contents.
  4268.      The `@top' command, which has a special use, is a member of this
  4269.      series (*note `@top': makeinfo top.).
  4270.    * The `@heading' series of commands produce unnumbered headings that
  4271.      do not appear in a table of contents.  The heading commands never
  4272.      start a new page.
  4273.    * The `@majorheading' command produces results similar to using the
  4274.      `@chapheading' command but generates a larger vertical whitespace
  4275.      before the heading.
  4276.    * When an `@setchapternewpage' command says to do so, the
  4277.      `@chapter', `@unnumbered', and `@appendix' commands start new
  4278.      pages in the printed manual; the `@heading' commands do not.
  4279.    Here are the four groups of chapter structuring commands:
  4280.                                                             No new pages
  4281.      Numbered       Unnumbered       Lettered and numbered  Unnumbered
  4282.      In contents    In contents          In contents        Not in contents
  4283.      
  4284.                     @top                                    @majorheading
  4285.      @chapter       @unnumbered          @appendix          @chapheading
  4286.      @section       @unnumberedsec       @appendixsec       @heading
  4287.      @subsection    @unnumberedsubsec    @appendixsubsec    @subheading
  4288.      @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
  4289. File: texi.info,  Node: makeinfo top,  Next: chapter,  Prev: Structuring Command Types,  Up: Structuring
  4290. `@top'
  4291. ======
  4292.    The `@top' command is a special sectioning command that you use only
  4293. after an `@node Top' line at the beginning of a Texinfo file.  The
  4294. `@top' command tells the `makeinfo' formatter which node is the `Top'
  4295. node.  It has the same typesetting effect as `@unnumbered' (*note
  4296. `@unnumbered': (`@appendix')unnumbered & appendix.).  For detailed
  4297. information, see *Note The `@top' Command: makeinfo top command.
  4298. File: texi.info,  Node: chapter,  Next: unnumbered & appendix,  Prev: makeinfo top,  Up: Structuring
  4299. `@chapter'
  4300. ==========
  4301.    `@chapter' identifies a chapter in the document.  Write the command
  4302. at the beginning of a line and follow it on the same line by the title
  4303. of the chapter.
  4304.    For example, this chapter in this manual is entitled "Chapter
  4305. Structuring"; the `@chapter' line looks like this:
  4306.      @chapter Chapter Structuring
  4307.    In TeX, the `@chapter' command creates a chapter in the document,
  4308. specifying the chapter title.  The chapter is numbered automatically.
  4309.    In Info, the `@chapter' command causes the title to appear on a line
  4310. by itself, with a line of asterisks inserted underneath.  Thus, in
  4311. Info, the above example produces the following output:
  4312.      Chapter Structuring
  4313.      *******************
  4314. File: texi.info,  Node: unnumbered & appendix,  Next: majorheading & chapheading,  Prev: chapter,  Up: Structuring
  4315. `@unnumbered', `@appendix'
  4316. ==========================
  4317.    Use the `@unnumbered' command to create a chapter that appears in a
  4318. printed manual without chapter numbers of any kind.  Use the
  4319. `@appendix' command to create an appendix in a printed manual that is
  4320. labelled by letter instead of by number.
  4321.    For Info file output, the `@unnumbered' and `@appendix' commands are
  4322. equivalent to `@chapter': the title is printed on a line by itself with
  4323. a line of asterisks underneath.  (*Note `@chapter': chapter.)
  4324.    To create an appendix or an unnumbered chapter, write an `@appendix'
  4325. or `@unnumbered' command at the beginning of a line and follow it on
  4326. the same line by the title, as you would if you were creating a chapter.
  4327. File: texi.info,  Node: majorheading & chapheading,  Next: section,  Prev: unnumbered & appendix,  Up: Structuring
  4328. `@majorheading', `@chapheading'
  4329. ===============================
  4330.    The `@majorheading' and `@chapheading' commands put chapter-like
  4331. headings in the body of a document.
  4332.    However, neither command causes TeX to produce a numbered heading or
  4333. an entry in the table of contents; and neither command causes TeX to
  4334. start a new page in a printed manual.
  4335.    In TeX, an `@majorheading' command generates a larger vertical
  4336. whitespace before the heading than an `@chapheading' command but is
  4337. otherwise the same.
  4338.    In Info, the `@majorheading' and `@chapheading' commands are
  4339. equivalent to `@chapter': the title is printed on a line by itself with
  4340. a line of asterisks underneath.  (*Note `@chapter': chapter.)
  4341. File: texi.info,  Node: section,  Next: unnumberedsec appendixsec heading,  Prev: majorheading & chapheading,  Up: Structuring
  4342. `@section'
  4343. ==========
  4344.    In a printed manual, an `@section' command identifies a numbered
  4345. section within a chapter.  The section title appears in the table of
  4346. contents.  In Info, an `@section' command provides a title for a
  4347. segment of text, underlined with `='.
  4348.    This section is headed with an `@section' command and looks like
  4349. this in the Texinfo file:
  4350.      @section @code{@@section}
  4351.    To create a section, write the `@section' command at the beginning
  4352. of a line and follow it on the same line by the section title.
  4353.    Thus,
  4354.      @section This is a section
  4355. produces
  4356.      This is a section
  4357.      =================
  4358. in Info.
  4359. File: texi.info,  Node: unnumberedsec appendixsec heading,  Next: subsection,  Prev: section,  Up: Structuring
  4360. `@unnumberedsec', `@appendixsec', `@heading'
  4361. ============================================
  4362.    The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
  4363. respectively, the unnumbered, appendix-like, and heading-like
  4364. equivalents of the `@section' command.  (*Note `@section': section.)
  4365. `@unnumberedsec'
  4366.      The `@unnumberedsec' command may be used within an unnumbered
  4367.      chapter or within a regular chapter or appendix to provide an
  4368.      unnumbered section.
  4369. `@appendixsec'
  4370. `@appendixsection'
  4371.      `@appendixsection' is a longer spelling of the `@appendixsec'
  4372.      command; the two are synonymous.
  4373.      Conventionally, the `@appendixsec' or `@appendixsection' command
  4374.      is used only within appendices.
  4375. `@heading'
  4376.      You may use the `@heading' command anywhere you wish for a
  4377.      section-style heading that will not appear in the table of
  4378.      contents.
  4379. File: texi.info,  Node: subsection,  Next: unnumberedsubsec appendixsubsec subheading,  Prev: unnumberedsec appendixsec heading,  Up: Structuring
  4380. The `@subsection' Command
  4381. =========================
  4382.    Subsections are to sections as sections are to chapters.  (*Note
  4383. `@section': section.)  In Info, subsection titles are underlined with
  4384. `-'.  For example,
  4385.      @subsection This is a subsection
  4386. produces
  4387.      This is a subsection
  4388.      --------------------
  4389.    In a printed manual, subsections are listed in the table of contents
  4390. and are numbered three levels deep.
  4391. File: texi.info,  Node: unnumberedsubsec appendixsubsec subheading,  Next: subsubsection,  Prev: subsection,  Up: Structuring
  4392. The `@subsection'-like Commands
  4393. ===============================
  4394.    The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
  4395. commands are, respectively, the unnumbered, appendix-like, and
  4396. heading-like equivalents of the `@subsection' command.  (*Note
  4397. `@subsection': subsection.)
  4398.    In Info, the `@subsection'-like commands generate a title underlined
  4399. with hyphens.  In a printed manual, an `@subheading' command produces a
  4400. heading like that of a subsection except that it is not numbered and
  4401. does not appear in the table of contents.  Similarly, an
  4402. `@unnumberedsubsec' command produces an unnumbered heading like that of
  4403. a subsection and an `@appendixsubsec' command produces a
  4404. subsection-like heading labelled with a letter and numbers; both of
  4405. these commands produce headings that appear in the table of contents.
  4406. File: texi.info,  Node: subsubsection,  Prev: unnumberedsubsec appendixsubsec subheading,  Up: Structuring
  4407. The `subsub' Commands
  4408. =====================
  4409.    The fourth and lowest level sectioning commands in Texinfo are the
  4410. `subsub' commands.  They are:
  4411. `@subsubsection'
  4412.      Subsubsections are to subsections as subsections are to sections.
  4413.      (*Note `@subsection': subsection.)  In a printed manual,
  4414.      subsubsection titles appear in the table of contents and are
  4415.      numbered four levels deep.
  4416. `@unnumberedsubsubsec'
  4417.      Unnumbered subsubsection titles appear in the table of contents of
  4418.      a printed manual, but lack numbers.  Otherwise, unnumbered
  4419.      subsubsections are the same as subsubsections.  In Info, unnumbered
  4420.      subsubsections look exactly like ordinary subsubsections.
  4421. `@appendixsubsubsec'
  4422.      Conventionally, appendix commands are used only for appendices and
  4423.      are lettered and numbered appropriately in a printed manual.  They
  4424.      also appear in the table of contents.  In Info, appendix
  4425.      subsubsections look exactly like ordinary subsubsections.
  4426. `@subsubheading'
  4427.      The `@subsubheading' command may be used anywhere that you need a
  4428.      small heading that will not appear in the table of contents.  In
  4429.      Info, subsubheadings look exactly like ordinary subsubsection
  4430.      headings.
  4431.    In Info,  `subsub' titles are underlined with periods.  For example,
  4432.      @subsubsection This is a subsubsection
  4433. produces
  4434.      This is a subsubsection
  4435.      .......................
  4436. File: texi.info,  Node: Nodes,  Next: Menus,  Prev: Structuring,  Up: Top
  4437. Nodes
  4438. *****
  4439.    "Nodes" are the primary segments of a Texinfo file.  They do not
  4440. themselves impose a hierarchic or any other kind of structure on a file.
  4441. Nodes contain "node pointers" that name other nodes, and can contain
  4442. "menus" which are lists of nodes.  In Info, the movement commands can
  4443. carry you to a pointed-to node or to a node listed in a menu.  Node
  4444. pointers and menus provide structure for Info files just as chapters,
  4445. sections, subsections, and the like, provide structure for printed
  4446. books.
  4447. * Menu:
  4448. * Two Paths::                   Different commands to structure
  4449.                                   Info output and printed output.
  4450. * Node Menu Illustration::      A diagram, and sample nodes and menus.
  4451. * node::                        How to write a node, in detail.
  4452. * makeinfo Pointer Creation::   How to create node pointers with `makeinfo'.
  4453. File: texi.info,  Node: Two Paths,  Next: Node Menu Illustration,  Up: Nodes
  4454. Two Paths
  4455. =========
  4456.    The node and menu commands and the chapter structuring commands are
  4457. independent of each other:
  4458.    * In Info, node and menu commands provide structure.  The chapter
  4459.      structuring commands generate headings with different kinds of
  4460.      underlining--asterisks for chapters, hyphens for sections, and so
  4461.      on; they do nothing else.
  4462.    * In TeX, the chapter structuring commands generate chapter and
  4463.      section numbers and tables of contents.  The node and menu
  4464.      commands provide information for cross references; they do nothing
  4465.      else.
  4466.    You can use node pointers and menus to structure an Info file any way
  4467. you want; and you can write a Texinfo file so that its Info output has a
  4468. different structure than its printed output.  However, most Texinfo
  4469. files are written such that the structure for the Info output
  4470. corresponds to the structure for the printed output.  It is not
  4471. convenient to do otherwise.
  4472.    Generally, printed output is structured in a tree-like hierarchy in
  4473. which the chapters are the major limbs from which the sections branch
  4474. out.  Similarly, node pointers and menus are organized to create a
  4475. matching structure in the Info output.
  4476. File: texi.info,  Node: Node Menu Illustration,  Next: node,  Prev: Two Paths,  Up: Nodes
  4477. Node and Menu Illustration
  4478. ==========================
  4479.    Here is a copy of the diagram shown earlier that illustrates a
  4480. Texinfo file with three chapters, each of which contains two sections.
  4481.    Note that the "root" is at the top of the diagram and the "leaves"
  4482. are at the bottom.  This is how such a diagram is drawn conventionally;
  4483. it illustrates an upside-down tree.  For this reason, the root node is
  4484. called the `Top' node, and `Up' node pointers carry you closer to the
  4485. root.
  4486.                                Top
  4487.                                 |
  4488.               -------------------------------------
  4489.              |                  |                  |
  4490.           Chapter 1          Chapter 2          Chapter 3
  4491.              |                  |                  |
  4492.           --------           --------           --------
  4493.          |        |         |        |         |        |
  4494.       Section  Section   Section  Section   Section  Section
  4495.         1.1      1.2       2.1      2.2       3.1      3.2
  4496.    Write the beginning of the node for Chapter 2 like this:
  4497.      @node     Chapter 2,  Chapter 3, Chapter 1, top
  4498.      @comment  node-name,  next,      previous,  up
  4499. This `@node' line says that the name of this node is "Chapter 2", the
  4500. name of the `Next' node is "Chapter 3", the name of the `Previous' node
  4501. is "Chapter 1", and the name of the `Up' node is "Top".
  4502.      *Please Note:* `Next' refers to the next node at the same
  4503.      hierarchical level in the manual, not necessarily to the next node
  4504.      within the Texinfo file.  In the Texinfo file, the subsequent node
  4505.      may be at a lower level--a section-level node may follow a
  4506.      chapter-level node, and a subsection-level node may follow a
  4507.      section-level node.  `Next' and `Previous' refer to nodes at the
  4508.      *same* hierarchical level.  (The `Top' node contains the exception
  4509.      to this rule.  Since the `Top' node is the only node at that
  4510.      level, `Next' refers to the first following node, which is almost
  4511.      always a chapter or chapter-level node.)
  4512.    To go to Sections 2.1 and 2.2 using Info, you need a menu inside
  4513. Chapter 2.  (*Note Menus::.)  You would write the menu just before the
  4514. beginning of Section 2.1, like this:
  4515.          @menu
  4516.          * Sect. 2.1::    Description of this section.
  4517.          * Sect. 2.2::
  4518.          @end menu
  4519.    Write the node for Sect. 2.1 like this:
  4520.          @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
  4521.          @comment  node-name, next,      previous,  up
  4522.    In Info format, the `Next' and `Previous' pointers of a node usually
  4523. lead to other nodes at the same level--from chapter to chapter or from
  4524. section to section (sometimes, as shown, the `Previous' pointer points
  4525. up); an `Up' pointer usually leads to a node at the level above (closer
  4526. to the `Top' node); and a `Menu' leads to nodes at a level below (closer
  4527. to `leaves').  (A cross reference can point to a node at any level; see
  4528. *Note Cross References::.)
  4529.    Usually, an `@node' command and a chapter structuring command are
  4530. used in sequence, along with indexing commands.  (You may follow the
  4531. `@node' line with a comment line that reminds you which pointer is
  4532. which.)
  4533.    Here is the beginning of the chapter in this manual called "Ending a
  4534. Texinfo File".  This shows an `@node' line followed by a comment line,
  4535. an `@chapter' line, and then by indexing lines.
  4536.      @node    Ending a File, Structuring, Beginning a File, Top
  4537.      @comment node-name,     next,        previous,         up
  4538.      @chapter Ending a Texinfo File
  4539.      @cindex Ending a Texinfo file
  4540.      @cindex Texinfo file ending
  4541.      @cindex File ending
  4542. File: texi.info,  Node: node,  Next: makeinfo Pointer Creation,  Prev: Node Menu Illustration,  Up: Nodes
  4543. The `@node' Command
  4544. ===================
  4545.    A "node" is a segment of text that begins at an `@node' command and
  4546. continues until the next `@node' command.  The definition of node is
  4547. different from that for chapter or section.  A chapter may contain
  4548. sections and a section may contain subsections; but a node cannot
  4549. contain subnodes; the text of a node continues only until the next
  4550. `@node' command in the file.  A node usually contains only one chapter
  4551. structuring command, the one that follows the `@node' line.  On the
  4552. other hand, in printed output nodes are used only for cross references,
  4553. so a chapter or section may contain any number of nodes.  Indeed, a
  4554. chapter usually contains several nodes, one for each section,
  4555. subsection, and subsubsection.
  4556.    To create a node, write an `@node' command at the beginning of a
  4557. line, and follow it with four arguments, separated by commas, on the
  4558. rest of the same line.  These arguments are the name of the node, and
  4559. the names of the `Next', `Previous', and `Up' pointers, in that order.
  4560. You may insert spaces before each pointer if you wish; the spaces are
  4561. ignored.  You must write the name of the node, and the names of the
  4562. `Next', `Previous', and `Up' pointers, all on the same line.  Otherwise,
  4563. the formatters fail.  (*note info: (info)Top, for more information
  4564. about nodes in Info.)
  4565.    Usually, you write one of the chapter-structuring command lines
  4566. immediately after an `@node' line--for example, an `@section' or
  4567. `@subsection' line.  (*Note Types of Structuring Command: Structuring
  4568. Command Types.)
  4569.      *Please note:* The GNU Emacs Texinfo mode updating commands work
  4570.      only with Texinfo files in which `@node' lines are followed by
  4571.      chapter structuring lines.  *Note Updating Requirements::.
  4572.    TeX uses `@node' lines to identify the names to use for cross
  4573. references.  For this reason, you must write `@node' lines in a Texinfo
  4574. file that you intend to format for printing, even if you do not intend
  4575. to format it for Info.  (Cross references, such as the one at the end
  4576. of this sentence, are made with `@xref' and its related commands; see
  4577. *Note Cross References::.)
  4578. * Menu:
  4579. * Node Names::                  How to choose node and pointer names.
  4580. * Writing a Node::              How to write an `@node' line.
  4581. * Node Line Tips::              Keep names short.
  4582. * Node Line Requirements::      Keep names unique, without @-commands.
  4583. * First Node::                  How to write a `Top' node.
  4584. * makeinfo top command::        How to use the `@top' command.
  4585. * Top Node Summary::            Write a brief description for readers.
  4586. File: texi.info,  Node: Node Names,  Next: Writing a Node,  Up: node
  4587. Choosing Node and Pointer Names
  4588. -------------------------------
  4589.    The name of a node identifies the node.  The pointers enable you to
  4590. reach other nodes and consist of the names of those nodes.
  4591.    Normally, a node's `Up' pointer contains the name of the node whose
  4592. menu mentions that node.  The node's `Next' pointer contains the name
  4593. of the node that follows that node in that menu and its `Previous'
  4594. pointer contains the name of the node that precedes it in that menu.
  4595. When a node's `Previous' node is the same as its `Up' node, both node
  4596. pointers name the same node.
  4597.    Usually, the first node of a Texinfo file is the `Top' node, and its
  4598. `Up' and `Previous' pointers point to the `dir' file, which contains
  4599. the main menu for all of Info.
  4600.    The `Top' node itself contains the main or master menu for the
  4601. manual.  Also, it is helpful to include a brief description of the
  4602. manual in the `Top' node.  *Note First Node::, for information on how
  4603. to write the first node of a Texinfo file.
  4604. File: texi.info,  Node: Writing a Node,  Next: Node Line Tips,  Prev: Node Names,  Up: node
  4605. How to Write an `@node' Line
  4606. ----------------------------
  4607.    The easiest way to write an `@node' line is to write `@node' at the
  4608. beginning of a line and then the name of the node, like this:
  4609.      @node NODE-NAME
  4610.    If you are using GNU Emacs, you can use the update node commands
  4611. provided by Texinfo mode to insert the names of the pointers; or you
  4612. can leave the pointers out of the Texinfo file and let `makeinfo'
  4613. insert node pointers into the Info file it creates.  (*Note Texinfo
  4614. Mode::, and *Note makeinfo Pointer Creation::.)
  4615.    Alternatively, you can insert the `Next', `Previous', and `Up'
  4616. pointers yourself.  If you do this, you may find it helpful to use the
  4617. Texinfo mode keyboard command `C-c C-c n'.  This command inserts
  4618. `@node' and a comment line listing the names of the pointers in their
  4619. proper order.  The comment line helps you keep track of which arguments
  4620. are for which pointers.  This comment line is especially useful if you
  4621. are not familiar with Texinfo.
  4622.    The template for a node line with `Next', `Previous', and `Up'
  4623. pointers looks like this:
  4624.      @node NODE-NAME, NEXT, PREVIOUS, UP
  4625.    If you wish, you can ignore `@node' lines altogether in your first
  4626. draft and then use the `texinfo-insert-node-lines' command to create
  4627. `@node' lines for you.  However, we do not recommend this practice.  It
  4628. is better to name the node itself at the same time that you write a
  4629. segment so you can easily make cross references.  A large number of
  4630. cross references are an especially important feature of a good Info
  4631. file.
  4632.    After you have inserted an `@node' line, you should immediately
  4633. write an @-command for the chapter or section and insert its name.
  4634. Next (and this is important!), put in several index entries.  Usually,
  4635. you will find at least two and often as many as four or five ways of
  4636. referring to the node in the index.  Use them all.  This will make it
  4637. much easier for people to find the node.
  4638. File: texi.info,  Node: Node Line Tips,  Next: Node Line Requirements,  Prev: Writing a Node,  Up: node
  4639. `@node' Line Tips
  4640. -----------------
  4641.    Here are three suggestions:
  4642.    * Try to pick node names that are informative but short.
  4643.      In the Info file, the file name, node name, and pointer names are
  4644.      all inserted on one line, which may run into the right edge of the
  4645.      window.  (This does not cause a problem with Info, but is ugly.)
  4646.    * Try to pick node names that differ from each other near the
  4647.      beginnings of their names.  This way, it is easy to use automatic
  4648.      name completion in Info.
  4649.    * By convention, node names are capitalized just as they would be for
  4650.      section or chapter titles--initial and significant words are
  4651.      capitalized; others are not.
  4652. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  4653. file texi.texi.
  4654.    This file documents Texinfo, a documentation system that uses a
  4655. single source file to produce both on-line information and a printed
  4656. manual.
  4657.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  4658.    This is the second edition of the Texinfo documentation,
  4659. and is consistent with version 2 of `texinfo.tex'.
  4660.    Permission is granted to make and distribute verbatim copies of this
  4661. manual provided the copyright notice and this permission notice are
  4662. preserved on all copies.
  4663.    Permission is granted to copy and distribute modified versions of
  4664. this manual under the conditions for verbatim copying, provided that
  4665. the entire resulting derived work is distributed under the terms of a
  4666. permission notice identical to this one.
  4667.    Permission is granted to copy and distribute translations of this
  4668. manual into another language, under the above conditions for modified
  4669. versions, except that this permission notice may be stated in a
  4670. translation approved by the Free Software Foundation.
  4671. File: texi.info,  Node: Node Line Requirements,  Next: First Node,  Prev: Node Line Tips,  Up: node
  4672. `@node' Line Requirements
  4673. -------------------------
  4674.    Here are several requirements for `@node' lines:
  4675.    * All the node names for a single Info file must be unique.
  4676.      Duplicates confuse the Info movement commands.  This means, for
  4677.      example, that if you end every chapter with a summary, you must
  4678.      name each summary node differently.  You cannot just call each one
  4679.      "Summary".  You may, however, duplicate the titles of chapters,
  4680.      sections, and the like.  Thus you can end each chapter in a book
  4681.      with a section called "Summary", so long as the node names for
  4682.      those sections are all different.
  4683.    * A pointer name must be the name of a node.
  4684.      The node to which a pointer points may come before or after the
  4685.      node containing the pointer.
  4686.    * You cannot use any of the Texinfo @-commands in a node name;
  4687.      @-commands confuse Info.
  4688.      Thus, the beginning of the section called `@chapter' looks like
  4689.      this:
  4690.           @node  chapter, unnumbered & appendix, makeinfo top, Structuring
  4691.           @comment  node-name,  next,  previous,  up
  4692.           @section @code{@@chapter}
  4693.           @findex chapter
  4694.    * You cannot use commas, colons, or apostrophes within a node name;
  4695.      these confuse TeX or the Info formatters.
  4696.      For example, the following is a section title:
  4697.           @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
  4698.      The corresponding node name is:
  4699.           unnumberedsec appendixsec heading
  4700.    * Case is significant.
  4701. File: texi.info,  Node: First Node,  Next: makeinfo top command,  Prev: Node Line Requirements,  Up: node
  4702. The First Node
  4703. --------------
  4704.    The first node of a Texinfo file is the `Top' node, except in an
  4705. included file (*note Include Files::.).
  4706.    The `Top' node (which must be named `top' or `Top') should have as
  4707. its `Up' and `Previous' nodes the name of a node in another file, where
  4708. there is a menu that leads to this file.  Specify the file name in
  4709. parentheses.  If the file is to be installed directly in the Info
  4710. directory file, use `(dir)' as the parent of the `Top' node; this is
  4711. short for `(dir)top', and specifies the `Top' node in the `dir' file,
  4712. which contains the main menu for Info.  For example, the `@node Top'
  4713. line of this manual looks like this:
  4714.      @node Top, Overview, (dir), (dir)
  4715. (You may use the Texinfo updating commands or the `makeinfo' utility to
  4716. insert these `Next' and `(dir)' pointers automatically.)
  4717.    *Note Install an Info File::, for more information about installing
  4718. an Info file in the `info' directory.
  4719.    The `Top' node contains the main or master menu for the document.
  4720. File: texi.info,  Node: makeinfo top command,  Next: Top Node Summary,  Prev: First Node,  Up: node
  4721. The `@top' Sectioning Command
  4722. -----------------------------
  4723.    A special sectioning command, `@top', has been created for use with
  4724. the `@node Top' line.  The `@top' sectioning command tells `makeinfo'
  4725. that it marks the `Top' node in the file.  It provides the information
  4726. that `makeinfo' needs to insert node pointers automatically.  Write the
  4727. `@top' command at the beginning of the line immediately following the
  4728. `@node Top' line.  Write the title on the remaining part of the same
  4729. line as the `@top' command.
  4730.    In Info, the `@top' sectioning command causes the title to appear on
  4731. a line by itself, with a line of asterisks inserted underneath.
  4732.    In TeX and `texinfo-format-buffer', the `@top' sectioning command is
  4733. merely a synonym for `@unnumbered'.  Neither of these formatters
  4734. require an `@top' command, and do nothing special with it.  You can use
  4735. `@chapter' or `@unnumbered' after the `@node Top' line when you use
  4736. these formatters.  Also, you can use `@chapter' or `@unnumbered' when
  4737. you use the Texinfo updating commands to create or update pointers and
  4738. menus.
  4739.    Whatever sectioning command follows an `@node Top' line, whether it
  4740. be `@top' or `@chapter', the `@node Top' line and the immediately
  4741. following line and any additional text must be enclosed between
  4742. `@ifinfo' and `@end ifinfo' commands.  (*Note Conditionals::.)  This
  4743. prevents the title and the accompanying text from appearing in printed
  4744. output.  Write the `@ifinfo' command before the `@node' line and write
  4745. the `@end ifinfo' command after the `@top' or other sectioning command
  4746. and after any additional text.  (You can write the `@end ifinfo'
  4747. command after the `@end menu' command if you like.)
  4748. File: texi.info,  Node: Top Node Summary,  Prev: makeinfo top command,  Up: node
  4749. The `Top' Node Summary
  4750. ----------------------
  4751.    You can help readers by writing a summary in the `Top' node, after
  4752. the `@top' line, before the main or master menu.  The summary should
  4753. briefly describe the Info file.  You should also write the version
  4754. number of the program to which the manual applies in this section.  This
  4755. helps the reader keep track of which manual is for which version of the
  4756. program.  If the manual changes more frequently than the program or is
  4757. independent of it, you should also include an edition number for the
  4758. manual.  (The title page should also contain this information: see
  4759. *Note `@titlepage': titlepage.)
  4760.    Put the whole of the `Top' node, including the `@top' sectioning
  4761. command line if you have one, between `@ifinfo' and `@end ifinfo' so
  4762. none of the text appears in the printed output (*note Conditionally
  4763. Visible Text: Conditionals.).  (You may want to repeat the brief
  4764. description from the `Top' node within `@iftex' ... `@end iftex' at the
  4765. beginning of the first chapter, for those who read the printed manual.)
  4766. File: texi.info,  Node: makeinfo Pointer Creation,  Prev: node,  Up: Nodes
  4767. Creating Pointers with `makeinfo'
  4768. =================================
  4769.    The `makeinfo' program has a feature for automatically creating node
  4770. pointers for a hierarchically organized file that lacks them.
  4771.    When you take advantage of this feature, you do not need to write the
  4772. `Next', `Previous', and `Up' pointers after the name of a node.
  4773. However, you must write a sectioning command, such as `@chapter' or
  4774. `@section', on the line immediately following each truncated `@node'
  4775. line.  You cannot write a comment line after a node line; the section
  4776. line must follow it immediately.
  4777.    In addition, you must follow the `Top' `@node' line with a line
  4778. beginning with `@top' to mark the `Top' node in the file. *Note `@top':
  4779. makeinfo top.
  4780.    Finally, you must write the name of each node (except for the `Top'
  4781. node) in a menu that is one or more hierarchical levels above the
  4782. node's hierarchical level.
  4783.    This node pointer insertion feature in `makeinfo' is an alternative
  4784. to the menu and pointer creation and update commands in Texinfo mode.
  4785. (*Note Updating Nodes and Menus::.)  It is especially helpful to people
  4786. who do not use GNU Emacs for writing Texinfo documents.
  4787. File: texi.info,  Node: Menus,  Next: Cross References,  Prev: Nodes,  Up: Top
  4788. Menus
  4789. *****
  4790.    "Menus" contain pointers to subordinate nodes.(1) In Info, you use
  4791. menus to go to such nodes.  Menus have no effect in printed manuals and
  4792. do not appear in them.
  4793.    By convention, a menu is put at the end of a node since a reader who
  4794. uses the menu may not see text that follows it.
  4795.    A node that has a menu should *not* contain much text.  If you have
  4796. a lot of text and a menu, move most of the text into a new subnode--all
  4797. but a few lines.
  4798. * Menu:
  4799. * Menu Location::               Put a menu in a short node.
  4800. * Writing a Menu::              What is a menu?
  4801. * Menu Parts::                  A menu entry has three parts.
  4802. * Less Cluttered Menu Entry::   Two part menu entry.
  4803. * Menu Example::                Two and three part menu entries.
  4804. * Other Info Files::            How to refer to a different Info file.
  4805.    ---------- Footnotes ----------
  4806.    (1)  Menus can carry you to any node, regardless of the hierarchical
  4807. structure; even to nodes in a different Info file.  However, the GNU
  4808. Emacs Texinfo mode updating commands work only to create menus of
  4809. subordinate nodes.  Conventionally, cross references are used to refer
  4810. to other nodes.
  4811. File: texi.info,  Node: Menu Location,  Next: Writing a Menu,  Up: Menus
  4812. Menus Need Short Nodes
  4813. ======================
  4814.    A reader can easily see a menu that is close to the beginning of the
  4815. node.  The node should be short.  As a practical matter, you should
  4816. locate a menu within 20 lines of the beginning of the node.  Otherwise,
  4817. a reader with a terminal that displays only a few lines may miss the
  4818. menu and its associated text.
  4819.    The short text before a menu may look awkward in a printed manual.
  4820. To avoid this, you can write a menu near the beginning of its node and
  4821. follow the menu by an `@node' line, and then an `@heading' line located
  4822. within `@ifinfo' and `@end ifinfo'.  This way, the menu, `@node' line,
  4823. and title appear only in the Info file, not the printed document.
  4824.    For example, the preceding two paragraphs follow an Info-only menu,
  4825. `@node' line, and heading, and look like this:
  4826.      @menu
  4827.      * Menu Location::             Put a menu in a short node.
  4828.      * Writing a Menu::            What is a menu?
  4829.      * Menu Parts::                A menu entry has three parts.
  4830.      * Less Cluttered Menu Entry:: Two part menu entry.
  4831.      * Menu Example::              Two and three part entries.
  4832.      * Other Info Files::          How to refer to a different
  4833.                                      Info file.
  4834.      @end menu
  4835.      
  4836.      @node Menu Location, Writing a Menu,  , Menus
  4837.      @ifinfo
  4838.      @heading Menus Need Short Nodes
  4839.      @end ifinfo
  4840.    The Texinfo file for this document contains more than a dozen
  4841. examples of this procedure.  One is at the beginning of this chapter;
  4842. another is at the beginning of the "Cross References" chapter.
  4843. File: texi.info,  Node: Writing a Menu,  Next: Menu Parts,  Prev: Menu Location,  Up: Menus
  4844. Writing a Menu
  4845. ==============
  4846.    A menu consists of an `@menu' command on a line by itself followed
  4847. by menu entry lines or menu comment lines and then by an `@end menu'
  4848. command on a line by itself.
  4849.    A menu looks like this:
  4850.      @menu
  4851.      Larger Units of Text
  4852.      
  4853.      * Files::                       All about handling files.
  4854.      * Multiples: Buffers.           Multiple buffers; editing
  4855.                                        several files at once.
  4856.      @end menu
  4857.    In a menu, every line that begins with an `* ' is a "menu entry".
  4858. (Note the space after the asterisk.)  A line that does not start with
  4859. an `* ' may also appear in a menu.  Such a line is not a menu entry but
  4860. is a menu comment line that appears in the Info file.  In the example
  4861. above, the line `Larger Units of Text' is a menu comment line; the two
  4862. lines starting with `* ' are menu entries.
  4863. File: texi.info,  Node: Menu Parts,  Next: Less Cluttered Menu Entry,  Prev: Writing a Menu,  Up: Menus
  4864. The Parts of a Menu
  4865. ===================
  4866.    A menu entry has three parts, only the second of which is required:
  4867.   1. The menu entry name.
  4868.   2. The name of the node (required).
  4869.   3. A description of the item.
  4870.    The template for a menu entry looks like this:
  4871.      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION
  4872.    Follow the menu entry name with a single colon and follow the node
  4873. name with tab, comma, period, or newline.
  4874.    In Info, a user selects a node with the `m' (`Info-menu') command.
  4875. The menu entry name is what the user types after the `m' command.
  4876.    The third part of a menu entry is a descriptive phrase or sentence.
  4877. Menu entry names and node names are often short; the description
  4878. explains to the reader what the node is about.  The description, which
  4879. is optional, can spread over two or more lines.  A useful description
  4880. complements the node name rather than repeats it.
  4881. File: texi.info,  Node: Less Cluttered Menu Entry,  Next: Menu Example,  Prev: Menu Parts,  Up: Menus
  4882. Less Cluttered Menu Entry
  4883. =========================
  4884.    When the menu entry name and node name are the same, you can write
  4885. the name immediately after the asterisk and space at the beginning of
  4886. the line and follow the name with two colons.
  4887.    For example, write
  4888.      * Name::                                    DESCRIPTION
  4889. instead of
  4890.      * Name: Name.                               DESCRIPTION
  4891.    You should use the node name for the menu entry name whenever
  4892. possible, since it reduces visual clutter in the menu.
  4893. File: texi.info,  Node: Menu Example,  Next: Other Info Files,  Prev: Less Cluttered Menu Entry,  Up: Menus
  4894. A Menu Example
  4895. ==============
  4896.    A menu looks like this in Texinfo:
  4897.      @menu
  4898.      * menu entry name: Node name.   A short description.
  4899.      * Node name::                   This form is preferred.
  4900.      @end menu
  4901. This produces:
  4902.      * menu:
  4903.      
  4904.      * menu entry name: Node name.   A short description.
  4905.      * Node name::                   This form is preferred.
  4906.    Here is an example as you might see it in a Texinfo file:
  4907.      @menu
  4908.      Larger Units of Text
  4909.      
  4910.      * Files::                       All about handling files.
  4911.      * Multiples: Buffers.           Multiple buffers; editing
  4912.                                        several files at once.
  4913.      @end menu
  4914. This produces:
  4915.      * menu:
  4916.      Larger Units of Text
  4917.      
  4918.      * Files::                       All about handling files.
  4919.      * Multiples: Buffers.           Multiple buffers; editing
  4920.                                        several files at once.
  4921.    In this example, the menu has two entries.  `Files' is both a menu
  4922. entry name and the name of the node referred to by that name.
  4923. `Multiples' is the menu entry name; it refers to the node named
  4924. `Buffers'. The line `Larger Units of Text' is a comment; it appears in
  4925. the menu, but is not an entry.
  4926.    Since no file name is specified with either `Files' or `Buffers',
  4927. they must be the names of nodes in the same Info file (*note Referring
  4928. to Other Info Files: Other Info Files.).
  4929. File: texi.info,  Node: Other Info Files,  Prev: Menu Example,  Up: Menus
  4930. Referring to Other Info Files
  4931. =============================
  4932.    You can create a menu entry that enables a reader in Info to go to a
  4933. node in another Info file by writing the file name in parentheses just
  4934. before the node name.  In this case, you should use the three-part menu
  4935. entry format, which saves the reader from having to type the file name.
  4936.    The format looks like this:
  4937.      @menu
  4938.      * FIRST-ENTRY-NAME:(FILENAME)NODENAME.     DESCRIPTION
  4939.      * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
  4940.      @end menu
  4941.    For example, to refer directly to the `Outlining' and `Rebinding'
  4942. nodes in the `Emacs Manual', you would write a menu like this:
  4943.      @menu
  4944.      * Outlining: (emacs)Outline Mode. The major mode for
  4945.                                        editing outlines.
  4946.      * Rebinding: (emacs)Rebinding.    How to redefine the
  4947.                                        meaning of a key.
  4948.      @end menu
  4949.    If you do not list the node name, but only name the file, then Info
  4950. presumes that you are referring to the `Top' node.
  4951.    The `dir' file that contains the main menu for Info has menu entries
  4952. that list only file names.  These take you directly to the `Top' nodes
  4953. of each Info document.  (*Note Install an Info File::.)
  4954.    For example:
  4955.      * Info: (info).         Documentation browsing system.
  4956.      * Emacs: (emacs).       The extensible, self-documenting
  4957.                              text editor.
  4958. (The `dir' top level directory for the Info system is an Info file, not
  4959. a Texinfo file, but a menu entry looks the same in both types of file.)
  4960.    Note that the GNU Emacs Texinfo mode menu updating commands only work
  4961. with nodes within the current buffer, so you cannot use them to create
  4962. menus that refer to other files.  You must write such menus by hand.
  4963. File: texi.info,  Node: Cross References,  Next: Marking Text,  Prev: Menus,  Up: Top
  4964. Cross References
  4965. ****************
  4966.    "Cross references" are used to refer the reader to other parts of the
  4967. same or different Texinfo files.  In Texinfo, nodes are the places to
  4968. which cross references can refer.
  4969. * Menu:
  4970. * References::                  What cross references are for.
  4971. * Cross Reference Commands::    A summary of the different commands.
  4972. * Cross Reference Parts::       A cross reference has several parts.
  4973. * xref::                        Begin a reference with `See' ...
  4974. * Top Node Naming::             How to refer to the beginning of another file.
  4975. * ref::                         A reference for the last part of a sentence.
  4976. * pxref::                       How to write a parenthetical cross reference.
  4977. * inforef::                     How to refer to an Info-only file.
  4978. File: texi.info,  Node: References,  Next: Cross Reference Commands,  Up: Cross References
  4979. What References Are For
  4980. =======================
  4981.    Often, but not always, a printed document should be designed so that
  4982. it can be read sequentially.  People tire of flipping back and forth to
  4983. find information that should be presented to them as they need it.
  4984.    However, in any document, some information will be too detailed for
  4985. the current context, or incidental to it; use cross references to
  4986. provide access to such information.  Also, an on-line help system or a
  4987. reference manual is not like a novel; few read such documents in
  4988. sequence from beginning to end.  Instead, people look up what they
  4989. need.  For this reason, such creations should contain many cross
  4990. references to help readers find other information that they may not
  4991. have read.
  4992.    In a printed manual, a cross reference results in a page reference,
  4993. unless it is to another manual altogether, in which case the cross
  4994. reference names that manual.
  4995.    In Info, a cross reference results in an entry that you can follow
  4996. using the Info `f' command.  (*note Some advanced Info commands:
  4997. (info)Help-Adv.)
  4998.    The various cross reference commands use nodes to define cross
  4999. reference locations.  This is evident in Info, in which a cross
  5000. reference takes you to the specified node.  TeX also uses nodes to
  5001. define cross reference locations, but the action is less obvious.  When
  5002. TeX generates a DVI file, it records nodes' page numbers and uses the
  5003. page numbers in making references.  Thus, if you are writing a manual
  5004. that will only be printed, and will not be used on-line, you must
  5005. nonetheless write `@node' lines to name the places to which you make
  5006. cross references.
  5007. File: texi.info,  Node: Cross Reference Commands,  Next: Cross Reference Parts,  Prev: References,  Up: Cross References
  5008. Different Cross Reference Commands
  5009. ==================================
  5010.    There are four different cross reference commands:
  5011. `@xref'
  5012.      Used to start a sentence in the printed manual saying `See ...' or
  5013.      an entry in the Info file saying `*Note ...'.
  5014. `@ref'
  5015.      Used within or, more often, at the end of a sentence; same as
  5016.      `@xref' for Info; produces just the reference in the printed
  5017.      manual without a preceding `See'.
  5018. `@pxref'
  5019.      Used within parentheses to make a reference that suits both an Info
  5020.      file and a printed book.  Starts with a lower case `see' within the
  5021.      printed manual. (`p' is for `parenthesis'.)
  5022. `@inforef'
  5023.      Used to make a reference to an Info file for which there is no
  5024.      printed manual.
  5025. (The `@cite' command is used to make references to books and manuals
  5026. for which there is no corresponding Info file and, therefore, no node
  5027. to which to point.   *Note `@cite': cite.)
  5028. File: texi.info,  Node: Cross Reference Parts,  Next: xref,  Prev: Cross Reference Commands,  Up: Cross References
  5029. Parts of a Cross Reference
  5030. ==========================
  5031.    A cross reference command requires only one argument, which is the
  5032. name of the node to which it refers.  But a cross reference command may
  5033. contain up to four additional arguments.  By using these arguments, you
  5034. can provide a cross reference name for Info, a topic description or
  5035. section title for the printed output, the name of a different Info
  5036. file, and the name of a different printed manual.
  5037.    Here is a simple cross reference example:
  5038.      @xref{Node name}.
  5039. which produces
  5040.      *Note Node name::.
  5041.      See Section NNN [Node name], page PPP.
  5042.    Here is an example of a full five-part cross reference:
  5043.      @xref{Node name, Cross Reference Name, Particular Topic,
  5044.      info-file-name, A Printed Manual}, for details.
  5045. which produces
  5046.      *Note Cross Reference Name: (info-file-name)Node name,
  5047.      for details.
  5048. in Info and
  5049.      See section "Particular Topic" in A Printed Manual, for details.
  5050. in a printed book.
  5051.    The five possible arguments for a cross reference are:
  5052.   1. The node name (required).  This is the node to which the cross
  5053.      reference takes you.  In a printed document, the location of the
  5054.      node provides the page reference only for references within the
  5055.      same document.
  5056.   2. The cross reference name for the Info reference, if it is to be
  5057.      different from the node name.  If you include this argument, it
  5058.      argument becomes the first part of the cross reference. It is
  5059.      usually omitted.
  5060.   3. A topic description or section name.  Often, this is the title of
  5061.      the section.  This is used as the name of the reference in the
  5062.      printed manual.  If omitted, the node name is used.
  5063.   4. The name of the Info file in which the reference is located, if it
  5064.      is different from the current file.
  5065.   5. The name of a printed manual from a different Texinfo file.
  5066.    The template for a full five argument cross reference looks like
  5067. this:
  5068.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
  5069.      INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
  5070.    Cross references with one, two, three, four, and five arguments are
  5071. described separately following the description of `@xref'.
  5072.    Write a node name in a cross reference in exactly the same way as in
  5073. the `@node' line, including the same capitalization; otherwise, the
  5074. formatters may not find the reference.
  5075.    You can write cross reference commands within a paragraph, but note
  5076. how Info and TeX format the output of each of the various commands:
  5077. write `@xref' at the beginning of a sentence; write `@pxref' only
  5078. within parentheses, and so on.
  5079. File: texi.info,  Node: xref,  Next: Top Node Naming,  Prev: Cross Reference Parts,  Up: Cross References
  5080. `@xref'
  5081. =======
  5082.    The `@xref' command generates a cross reference for the beginning of
  5083. a sentence.  The Info formatting commands convert it into an Info cross
  5084. reference, which the Info `f' command can use to bring you directly to
  5085. another node.  The TeX typesetting commands convert it into a page
  5086. reference, or a reference to another book or manual.
  5087. * Menu:
  5088. * Reference Syntax::            What a reference looks like and requires.
  5089. * One Argument::                `@xref' with one argument.
  5090. * Two Arguments::               `@xref' with two arguments.
  5091. * Three Arguments::             `@xref' with three arguments.
  5092. * Four and Five Arguments::     `@xref' with four and five arguments.
  5093. File: texi.info,  Node: Reference Syntax,  Next: One Argument,  Up: xref
  5094. What a Reference Looks Like and Requires
  5095. ----------------------------------------
  5096.    Most often, an Info cross reference looks like this:
  5097.      *Note NODE-NAME::.
  5098. or like this
  5099.      *Note CROSS-REFERENCE-NAME: NODE-NAME.
  5100. In TeX, a cross reference looks like this:
  5101.      See Section SECTION-NUMBER [NODE-NAME], page PAGE.
  5102. or like this
  5103.      See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
  5104.    The `@xref' command does not generate a period or comma to end the
  5105. cross reference in either the Info file or the printed output.  You
  5106. must write that period or comma yourself; otherwise, Info will not
  5107. recognize the end of the reference.  (The `@pxref' command works
  5108. differently.  *Note `@pxref': pxref.)
  5109.      *Please note:* A period or comma *must* follow the closing brace
  5110.      of an `@xref'.  It is required to terminate the cross reference.
  5111.      This period or comma will appear in the output, both in the Info
  5112.      file and in the printed manual.
  5113.    `@xref' must refer to an Info node by name.  Use `@node' to define
  5114. the node (*note Writing a Node::.).
  5115.    `@xref' is followed by several arguments inside braces, separated by
  5116. commas.  Whitespace before and after these commas is ignored.
  5117.    A cross reference requires only the name of a node; but it may
  5118. contain up to four additional arguments.  Each of these variations
  5119. produces a cross reference that looks somewhat different.
  5120.      *Please note:* Commas separate arguments in a cross reference;
  5121.      avoid including them in the title or other part lest the formatters
  5122.      mistake them for separators.
  5123. File: texi.info,  Node: One Argument,  Next: Two Arguments,  Prev: Reference Syntax,  Up: xref
  5124. `@xref' with One Argument
  5125. -------------------------
  5126.    The simplest form of `@xref' takes one argument, the name of another
  5127. node in the same Info file.    The Info formatters produce output that
  5128. the Info readers can use to jump to the reference; TeX produces output
  5129. that specifies the page and section number for you.
  5130. For example,
  5131.      @xref{Tropical Storms}.
  5132. produces
  5133.      *Note Tropical Storms::.
  5134.      See Section 3.1 [Tropical Storms], page 24.
  5135. (Note that in the preceding example the closing brace is followed by a
  5136. period.)
  5137.    You can write a clause after the cross reference, like this:
  5138.      @xref{Tropical Storms}, for more info.
  5139. which produces
  5140.      *Note Tropical Storms::, for more info.
  5141.      See Section 3.1 [Tropical Storms], page 24, for more info.
  5142. (Note that in the preceding example the closing brace is followed by a
  5143. comma, and then by the clause, which is followed by a period.)
  5144. File: texi.info,  Node: Two Arguments,  Next: Three Arguments,  Prev: One Argument,  Up: xref
  5145. `@xref' with Two Arguments
  5146. --------------------------
  5147.    With two arguments, the second is used as the name of the Info cross
  5148. reference, while the first is still the name of the node to which the
  5149. cross reference points.
  5150. The template is like this:
  5151.      @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
  5152. For example,
  5153.      @xref{Electrical Effects, Lightning}.
  5154. produces:
  5155.      *Note Lightning: Electrical Effects.
  5156.      See Section 5.2 [Electrical Effects], page 57.
  5157. (Note that in the preceding example the closing brace is followed by a
  5158. period; and that the node name is printed, not the cross reference
  5159. name.)
  5160.    You can write a clause after the cross reference, like this:
  5161.      @xref{Electrical Effects, Lightning}, for more info.
  5162. which produces
  5163.      *Note Lightning: Electrical Effects, for more info.
  5164.      See Section 5.2 [Electrical Effects], page 57, for more info.
  5165. (Note that in the preceding example the closing brace is followed by a
  5166. comma, and then by the clause, which is followed by a period.)
  5167. File: texi.info,  Node: Three Arguments,  Next: Four and Five Arguments,  Prev: Two Arguments,  Up: xref
  5168. `@xref' with Three Arguments
  5169. ----------------------------
  5170.    A third argument replaces the node name in the TeX output.  The third
  5171. argument should be the name of the section in the printed output, or
  5172. else state the topic discussed by that section.  Often, you will want to
  5173. use initial upper case letters so it will be easier to read when the
  5174. reference is printed.  Use a third argument when the node name is
  5175. unsuitable because of syntax or meaning.
  5176.    Remember to avoid placing a comma within the title or topic section
  5177. of a cross reference, or within any other section.  The formatters
  5178. divide cross references into arguments according to the commas; a comma
  5179. within a title or other section will divide it into two arguments.  In
  5180. a reference, you need to write a title such as "Clouds, Mist, and Fog"
  5181. without the commas.
  5182.    Also, remember to write a comma or period after the closing brace of
  5183. a `@xref' to terminate the cross reference.  In the following examples,
  5184. a clause follows a terminating comma.
  5185. The template is like this:
  5186.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
  5187. For example,
  5188.      @xref{Electrical Effects, Lightning, Thunder and Lightning},
  5189.      for details.
  5190. produces
  5191.      *Note Lightning: Electrical Effects, for details.
  5192.      See Section 5.2 [Thunder and Lightning], page 57, for details.
  5193.    If a third argument is given and the second one is empty, then the
  5194. third argument serves both.  (Note how two commas, side by side, mark
  5195. the empty second argument.)
  5196.      @xref{Electrical Effects, , Thunder and Lightning},
  5197.      for details.
  5198. produces
  5199.      *Note Thunder and Lightning: Electrical Effects, for details.
  5200.      See Section 5.2 [Thunder and Lightning], page 57, for details.
  5201.    As a practical matter, it is often best to write cross references
  5202. with just the first argument if the node name and the section title are
  5203. the same, and with the first and third arguments if the node name and
  5204. title are different.
  5205.    Here are several examples from `The GAWK Manual':
  5206.      @xref{Sample Program}.
  5207.      @xref{Glossary}.
  5208.      @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
  5209.      @xref{Close Output, , Closing Output Files and Pipes},
  5210.         for more information.
  5211.      @xref{Regexp, , Regular Expressions as Patterns}.
  5212. File: texi.info,  Node: Four and Five Arguments,  Prev: Three Arguments,  Up: xref
  5213. `@xref' with Four and Five Arguments
  5214. ------------------------------------
  5215.    In a cross reference, a fourth argument specifies the name of another
  5216. Info file, different from the file in which the reference appears, and
  5217. a fifth argument specifies its title as a printed manual.
  5218.    Remember that a comma or period must follow the closing brace of an
  5219. `@xref' command to terminate the cross reference.  In the following
  5220. examples, a clause follows a terminating comma.
  5221. The template is:
  5222.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
  5223.      INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
  5224. For example,
  5225.      @xref{Electrical Effects, Lightning, Thunder and Lightning,
  5226.      weather, An Introduction to Meteorology}, for details.
  5227. produces
  5228.      *Note Lightning: (weather)Electrical Effects, for details.
  5229. The name of the Info file is enclosed in parentheses and precedes the
  5230. name of the node.
  5231. In a printed manual, the reference looks like this:
  5232.      See section "Thunder and Lightning" in An Introduction to
  5233.      Meteorology, for details.
  5234. The title of the printed manual is typeset in italics; and the
  5235. reference lacks a page number since TeX cannot know to which page a
  5236. reference refers when that reference is to another manual.
  5237.    Often, you will leave out the second argument when you use the long
  5238. version of `@xref'.  In this case, the third argument, the topic
  5239. description, will be used as the cross reference name in Info.
  5240. The template looks like this:
  5241.      @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
  5242.      PRINTED-MANUAL-TITLE}, for details.
  5243. which produces
  5244.      *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
  5245.      See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
  5246. For example,
  5247.      @xref{Electrical Effects, , Thunder and Lightning,
  5248.      weather, An Introduction to Meteorology}, for details.
  5249. produces
  5250.      *Note Thunder and Lightning: (weather)Electrical Effects,
  5251.      for details.
  5252.      See section "Thunder and Lightning" in An Introduction to
  5253.      Meteorology, for details.
  5254.    On rare occasions, you may want to refer to another Info file that
  5255. is within a single printed manual--when multiple Texinfo files are
  5256. incorporated into the same TeX run but make separate Info files.  In
  5257. this case, you need to specify only the fourth argument, and not the
  5258. fifth.
  5259. File: texi.info,  Node: Top Node Naming,  Next: ref,  Prev: xref,  Up: Cross References
  5260. Naming a `Top' Node
  5261. ===================
  5262.    In a cross reference, you must always name a node.  This means that
  5263. in order to refer to a whole manual, you must identify the `Top' node by
  5264. writing it as the first argument to the `@xref' command.  (This is
  5265. different from the way you write a menu entry; see *Note Referring to
  5266. Other Info Files: Other Info Files.)  At the same time, to provide a
  5267. meaningful section topic or title in the printed cross reference
  5268. (instead of the word `Top'), you must write an appropriate entry for
  5269. the third argument to the `@xref' command.
  5270. Thus, to make a cross reference to `The GNU Make Manual', write:
  5271.      @xref{Top, , Overview, make, The GNU Make Manual}.
  5272. which produces
  5273.      *Note Overview: (make)Top.
  5274.      See section "Overview" in The GNU Make Manual.
  5275. In this example, `Top' is the name of the first node, and `Overview' is
  5276. the name of the first section of the manual.
  5277. File: texi.info,  Node: ref,  Next: pxref,  Prev: Top Node Naming,  Up: Cross References
  5278. `@ref'
  5279. ======
  5280.    `@ref' is nearly the same as `@xref' except that it does not
  5281. generate a `See' in the printed output, just the reference itself.
  5282. This makes it useful as the last part of a sentence.
  5283. For example,
  5284.      For more information, see @ref{Hurricanes}.
  5285. produces
  5286.      For more information, see *Note Hurricanes.
  5287.      For more information, see Section 8.2 [Hurricanes], page 123.
  5288.    The `@ref' command sometimes leads writers to express themselves in
  5289. a manner that is suitable for a printed manual but looks awkward in the
  5290. Info format.  Bear in mind that your audience will be using both the
  5291. printed and the Info format.
  5292. For example,
  5293.      Sea surges are described in @ref{Hurricanes}.
  5294. produces
  5295.      Sea surges are described in Section 6.7 [Hurricanes], page 72.
  5296. in a printed document, and the following in Info:
  5297.      Sea surges are described in *Note Hurricanes::.
  5298.      *Caution:* You *must* write a period or comma immediately after an
  5299.      `@ref' command with two or more arguments.  Otherwise, Info will
  5300.      not find the end of the cross reference entry and its attempt to
  5301.      follow the cross reference will fail.  As a general rule, you
  5302.      should write a period or comma after every `@ref' command.  This
  5303.      looks best in both the printed and the Info output.
  5304. File: texi.info,  Node: pxref,  Next: inforef,  Prev: ref,  Up: Cross References
  5305. `@pxref'
  5306. ========
  5307.    The parenthetical reference command, `@pxref', is nearly the same as
  5308. `@xref', but you use it *only* inside parentheses and you do *not* type
  5309. a comma or period after the command's closing brace.  The command
  5310. differs from `@xref' in two ways:
  5311.   1. TeX typesets the reference for the printed manual with a lower case
  5312.      `see' rather than an upper case `See'.
  5313.   2. The Info formatting commands automatically end the reference with a
  5314.      closing colon or period.
  5315.    Because one type of formatting automatically inserts closing
  5316. punctuation and the other does not, you should use `@pxref' *only*
  5317. inside parentheses as part of another sentence.  Also, you yourself
  5318. should not insert punctuation after the reference, as you do with
  5319. `@xref'.
  5320.    `@pxref' is designed so that the output looks right and works right
  5321. between parentheses both in printed output and in an Info file.  In a
  5322. printed manual, a closing comma or period should not follow a cross
  5323. reference within parentheses; such punctuation is wrong.  But in an
  5324. Info file, suitable closing punctuation must follow the cross reference
  5325. so Info can recognize its end.  `@pxref' spares you the need to use
  5326. complicated methods to put a terminator into one form of the output and
  5327. not the other.
  5328. With one argument, a parenthetical cross reference looks like this:
  5329.      ... storms cause flooding (@pxref{Hurricanes}) ...
  5330. which produces
  5331.      ... storms cause flooding (*Note Hurricanes::) ...
  5332.      ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
  5333.      ...
  5334.    With two arguments, a parenthetical cross reference has this
  5335. template:
  5336.      ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
  5337. which produces
  5338.      ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
  5339.      ... (see Section NNN [NODE-NAME], page PPP) ...
  5340.    `@pxref' can be used with up to five arguments just like `@xref'
  5341. (*note `@xref': xref.).
  5342.      *Please note:* Use `@pxref' only as a parenthetical reference.  Do
  5343.      not try to use `@pxref' as a clause in a sentence.  It will look
  5344.      bad in either the Info file, the printed output, or both.
  5345.      Also, parenthetical cross references look best at the ends of
  5346.      sentences.  Although you may write them in the middle of a
  5347.      sentence, that location breaks up the flow of text.
  5348. File: texi.info,  Node: inforef,  Prev: pxref,  Up: Cross References
  5349. `@inforef'
  5350. ==========
  5351.    `@inforef' is used for cross references to Info files for which
  5352. there are no printed manuals.  Even in a printed manual, `@inforef'
  5353. generates a reference directing the user to look in an Info file.
  5354.    The command takes either two or three arguments, in the following
  5355. order:
  5356.   1. The node name.
  5357.   2. The cross reference name (optional).
  5358.   3. The Info file name.
  5359. Separate the arguments with commas, as with `@xref'.  Also, you must
  5360. terminate the reference with a comma or period after the `}', as you do
  5361. with `@xref'.
  5362. The template is:
  5363.      @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
  5364. Thus,
  5365.      @inforef{Expert, Advanced Info commands, info},
  5366.      for more information.
  5367. produces
  5368.      *Note Advanced Info commands: (info)Expert,
  5369.      for more information.
  5370.      See Info file `info', node `Expert', for more information.
  5371. Similarly,
  5372.      @inforef{Expert, , info}, for more information.
  5373. produces
  5374.      *Note (info)Expert::, for more information.
  5375.      See Info file `info', node `Expert', for more information.
  5376.    The converse of `@inforef' is `@cite', which is used to refer to
  5377. printed works for which no Info form exists.  *Note `@cite': cite.
  5378. File: texi.info,  Node: Marking Text,  Next: Quotations and Examples,  Prev: Cross References,  Up: Top
  5379. Marking Words and Phrases
  5380. *************************
  5381.    In Texinfo, you can mark words and phrases in a variety of ways.
  5382. The Texinfo formatters use this information to determine how to
  5383. highlight the text.  You can specify, for example, whether a word or
  5384. phrase is a defining occurrence, a metasyntactic variable, or a symbol
  5385. used in a program.  Also, you can emphasize text.
  5386. * Menu:
  5387. * Indicating::                  How to indicate definitions, files, etc.
  5388. * Emphasis::                    How to emphasize text.
  5389. File: texi.info,  Node: Indicating,  Next: Emphasis,  Up: Marking Text
  5390. Indicating Definitions, Commands, etc.
  5391. ======================================
  5392.    Texinfo has commands for indicating just what kind of object a piece
  5393. of text refers to.  For example, metasyntactic variables are marked by
  5394. `@var', and code by `@code'.  Since the pieces of text are labelled by
  5395. commands that tell what kind of object they are, it is easy to change
  5396. the way the Texinfo formatters prepare such text.  (Texinfo is an
  5397. *intentional* formatting language rather than a *typesetting*
  5398. formatting language.)
  5399.    For example, in a printed manual, code is usually illustrated in a
  5400. typewriter font; `@code' tells TeX to typeset this text in this font.
  5401. But it would be easy to change the way TeX highlights code to use
  5402. another font, and this change would not effect how keystroke examples
  5403. are highlighted.  If straight typesetting commands were used in the body
  5404. of the file and you wanted to make a change, you would need to check
  5405. every single occurrence to make sure that you were changing code and
  5406. not something else that should not be changed.
  5407. * Menu:
  5408. * Useful Highlighting::         Highlighting provides useful information.
  5409. * code::                        How to indicate code.
  5410. * kbd::                         How to show keyboard input.
  5411. * key::                         How to specify keys.
  5412. * samp::                        How to show a literal sequence of characters.
  5413. * var::                         How to indicate a metasyntactic variable.
  5414. * file::                        How to indicate the name of a file.
  5415. * dfn::                         How to specify a definition.
  5416. * cite::                        How to refer to a book that is not in Info.
  5417. File: texi.info,  Node: Useful Highlighting,  Next: code,  Up: Indicating
  5418. Highlighting Commands are Useful
  5419. --------------------------------
  5420.    The highlighting commands can be used to generate useful information
  5421. from the file, such as lists of functions or file names.  It is
  5422. possible, for example, to write a program in Emacs Lisp (or a keyboard
  5423. macro) to insert an index entry after every paragraph that contains
  5424. words or phrases marked by a specified command.  You could do this to
  5425. construct an index of functions if you had not already made the entries.
  5426.    The commands serve a variety of purposes:
  5427. `@code{SAMPLE-CODE}'
  5428.      Indicate text that is a literal example of a piece of a program.
  5429. `@kbd{KEYBOARD-CHARACTERS}'
  5430.      Indicate keyboard input.
  5431. `@key{KEY-NAME}'
  5432.      Indicate the conventional name for a key on a keyboard.
  5433. `@samp{TEXT}'
  5434.      Indicate text that is a literal example of a sequence of
  5435.      characters.
  5436. `@var{METASYNTACTIC-VARIABLE}'
  5437.      Indicate a metasyntactic variable.
  5438. `@file{FILE-NAME}'
  5439.      Indicate the name of a file.
  5440. `@dfn{TERM}'
  5441.      Indicate the introductory or defining use of a term.
  5442. `@cite{REFERENCE}'
  5443.      Indicate the name of a book.
  5444. File: texi.info,  Node: code,  Next: kbd,  Prev: Useful Highlighting,  Up: Indicating
  5445. `@code'{SAMPLE-CODE}
  5446. --------------------
  5447.    Use the `@code' command to indicate text that is a piece of a
  5448. program and which consists of entire syntactic tokens.  Enclose the
  5449. text in braces.
  5450.    Thus, you should use `@code' for an expression in a program, for the
  5451. name of a variable or function used in a program, or for a keyword.
  5452. Also, you should use `@code' for the name of a program, such as `diff',
  5453. that is a name used in the machine. (You should write the name of a
  5454. program in the ordinary text font if you regard it as a new English
  5455. word, such as `Emacs' or `Bison'.)
  5456.    Use `@code' for environment variables such as `TEXINPUTS', and other
  5457. variables.
  5458.    Use `@code' for command names in command languages that resemble
  5459. programming languages, such as Texinfo or the shell.  For example,
  5460. `@code' and `@samp' are produced by writing `@code{@@code}' and
  5461. `@code{@@samp}' in the Texinfo source, respectively.
  5462.    Note, however, that you should not use `@code' for shell options
  5463. such as `-c' when such options stand alone. (Use `@samp'.) Also, an
  5464. entire shell command often looks better if written using `@samp' rather
  5465. than `@code'.  In this case, the rule is to choose the more pleasing
  5466. format.
  5467.    It is incorrect to alter the case of a word inside an `@code'
  5468. command when it appears at the beginning of a sentence.  Most computer
  5469. languages are case sensitive.  In C, for example, `Printf' is different
  5470. from the identifier `printf', and most likely is a misspelling of it.
  5471. Even in languages which are not case sensitive, it is confusing to a
  5472. human reader to see identifiers spelled in different ways.  Pick one
  5473. spelling and always use that.  If you do not want to start a sentence
  5474. with a command written all in lower case, you should rearrange the
  5475. sentence.
  5476.    Do not use the `@code' command for a string of characters shorter
  5477. than a syntactic token.  If you are writing about `TEXINPU', which is
  5478. just a part of the name for the `TEXINPUTS' environment variable, you
  5479. should use `@samp'.
  5480.    In particular, you should not use the `@code' command when writing
  5481. about the characters used in a token; do not, for example, use `@code'
  5482. when you are explaining what letters or printable symbols can be used
  5483. in the names of functions.  (Use `@samp'.)  Also, you should not use
  5484. `@code' to mark text that is considered input to programs unless the
  5485. input is written in a language that is like a programming language.
  5486. For example, you should not use `@code' for the keystroke commands of
  5487. GNU Emacs (use `@kbd' instead) although you may use `@code' for the
  5488. names of the Emacs Lisp functions that the keystroke commands invoke.
  5489.    In the printed manual, `@code' causes TeX to typeset the argument in
  5490. a typewriter face.  In the Info file, it causes the Info formatting
  5491. commands to use single quotation marks around the text.
  5492.    For example,
  5493.      Use @code{diff} to compare two files.
  5494. produces this in the printed manual:
  5495.      Use `diff' to compare two files.
  5496. File: texi.info,  Node: kbd,  Next: key,  Prev: code,  Up: Indicating
  5497. `@kbd'{KEYBOARD-CHARACTERS}
  5498. ---------------------------
  5499.    Use the `@kbd' command for characters of input to be typed by users.
  5500. For example, to refer to the characters `M-a', write
  5501.      @kbd{M-a}
  5502. and to refer to the characters `M-x shell', write
  5503.      @kbd{M-x shell}
  5504.    The `@kbd' command has the same effect as `@code' in Info, but may
  5505. produce a different font in a printed manual.
  5506.    You can embed another @-command inside the braces of an `@kbd'
  5507. command.  Here, for example, is the way to describe a command that
  5508. would be described more verbosely as "press an `r' and then press the
  5509. RET key":
  5510.      @kbd{r @key{RET}}
  5511. This produces: `r RET'
  5512.    You also use the `@kbd' command if you are spelling out the letters
  5513. you type; for example:
  5514.      To give the @code{logout} command,
  5515.      type the characters @kbd{l o g o u t @key{RET}}.
  5516. This produces:
  5517.      To give the `logout' command, type the characters `l o g o u t
  5518.      RET'.
  5519.    (Also, this example shows that you can add spaces for clarity.  If
  5520. you really want to mention a space character as one of the characters of
  5521. input, write `@key{SPC}' for it.)
  5522. File: texi.info,  Node: key,  Next: samp,  Prev: kbd,  Up: Indicating
  5523. `@key'{KEY-NAME}
  5524. ----------------
  5525.    Use the `@key' command for the conventional name for a key on a
  5526. keyboard, as in:
  5527.      @key{RET}
  5528.    You can use the `@key' command within the argument of an `@kbd'
  5529. command when the sequence of characters to be typed includes one or
  5530. more keys that are described by name.
  5531.    For example, to produce `C-x ESC' you would type:
  5532.      @kbd{C-x @key{ESC}}
  5533.    Here is a list of the recommended names for keys; they are all in
  5534. upper case:
  5535.     SPC
  5536.           Space
  5537.     RET
  5538.           Return
  5539.     LFD
  5540.           Linefeed
  5541.     TAB
  5542.           Tab
  5543.     BS
  5544.           Backspace
  5545.     ESC
  5546.           Escape
  5547.     DEL
  5548.           Delete
  5549.     SFT
  5550.           Shift
  5551.     CTL
  5552.           Control
  5553.     META
  5554.           Meta
  5555.    There are subtleties to handling words like `meta' or `ctl' that are
  5556. names of shift keys.  When mentioning a character in which the shift
  5557. key is used, such as `Meta-a', use the `@kbd' command alone; do not use
  5558. the `@key' command; but when you are referring to the shift key in
  5559. isolation, use the `@key' command.  For example, write `@kbd{Meta-a}'
  5560. to produce `Meta-a' and `@key{META}' to produce META.  This is because
  5561. `Meta-a' refers to keys that you press on a keyboard, but META refers
  5562. to a key without implying that you press it.  In short, use `@kbd' for
  5563. what you do, and use `@key' for what you talk about: "Press `@kbd{M-a}'
  5564. to move point to the beginning of the sentence.  The `@key{META}' key
  5565. is often in the lower left of the keyboard."
  5566. File: texi.info,  Node: samp,  Next: var,  Prev: key,  Up: Indicating
  5567. `@samp'{TEXT}
  5568. -------------
  5569.    Use the `@samp' command to indicate text that is a literal example
  5570. or `sample' of a sequence of characters in a file, string, pattern, etc.
  5571. Enclose the text in braces.  The argument appears within single
  5572. quotation marks in both the Info file and the printed manual; in
  5573. addition, it is printed in a fixed-width font.
  5574.      To match @samp{foo} at the end of the line,
  5575.      use the regexp @samp{foo$}.
  5576. produces
  5577.      To match `foo' at the end of the line, use the regexp `foo$'.
  5578.    Any time you are referring to single characters, you should use
  5579. `@samp' unless `@kbd' is more appropriate.  Use `@samp' for the names
  5580. of command-line options.  Also, you may use `@samp' for entire
  5581. statements in C and for entire shell commands--in this case, `@samp'
  5582. often looks better than `@code'.  Basically, `@samp' is a catchall for
  5583. whatever is not covered by `@code', `@kbd', or `@key'.
  5584.    Only include punctuation marks within braces if they are part of the
  5585. string you are specifying.  Write punctuation marks outside the braces
  5586. if those punctuation marks are part of the English text that surrounds
  5587. the string.  In the following sentence, for example, the commas and
  5588. period are outside of the braces:
  5589.      In English, the vowels are @samp{a}, @samp{e},
  5590.      @samp{i}, @samp{o}, @samp{u}, and sometimes
  5591.      @samp{y}.
  5592. This produces:
  5593.      In English, the vowels are `a', `e', `i', `o', `u',  and sometimes
  5594.      `y'.
  5595. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  5596. file texi.texi.
  5597.    This file documents Texinfo, a documentation system that uses a
  5598. single source file to produce both on-line information and a printed
  5599. manual.
  5600.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  5601.    This is the second edition of the Texinfo documentation,
  5602. and is consistent with version 2 of `texinfo.tex'.
  5603.    Permission is granted to make and distribute verbatim copies of this
  5604. manual provided the copyright notice and this permission notice are
  5605. preserved on all copies.
  5606.    Permission is granted to copy and distribute modified versions of
  5607. this manual under the conditions for verbatim copying, provided that
  5608. the entire resulting derived work is distributed under the terms of a
  5609. permission notice identical to this one.
  5610.    Permission is granted to copy and distribute translations of this
  5611. manual into another language, under the above conditions for modified
  5612. versions, except that this permission notice may be stated in a
  5613. translation approved by the Free Software Foundation.
  5614. File: texi.info,  Node: var,  Next: file,  Prev: samp,  Up: Indicating
  5615. `@var'{METASYNTACTIC-VARIABLE}
  5616. ------------------------------
  5617.    Use the `@var' command to indicate metasyntactic variables.  A
  5618. "metasyntactic variable" is something that stands for another piece of
  5619. text.  For example, you should use a metasyntactic variable in the
  5620. documentation of a function to describe the arguments that are passed
  5621. to that function.
  5622.    Do not use `@var' for the names of particular variables in
  5623. programming languages.  These are specific names from a program, so
  5624. `@code' is correct for them.  For example, the Lisp variable
  5625. `texinfo-tex-command' is not a metasyntactic variable; it is properly
  5626. formatted using `@code'.
  5627.    The effect of `@var' in the Info file is to change the case of the
  5628. argument to all upper case; in the printed manual, to italicize it.
  5629.    For example,
  5630.      To delete file @var{filename},
  5631.      type @code{rm @var{filename}}.
  5632. produces
  5633.      To delete file FILENAME, type `rm FILENAME'.
  5634. (Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
  5635.    Write a metasyntactic variable all in lower case without spaces, and
  5636. use hyphens to make it more readable.  Thus, the Texinfo source for the
  5637. illustration of how to begin a Texinfo manual looks like this:
  5638.      \input texinfo
  5639.      @@setfilename @var{info-file-name}
  5640.      @@settitle @var{name-of-manual}
  5641. This produces:
  5642.      \input texinfo
  5643.      @setfilename INFO-FILE-NAME
  5644.      @settitle NAME-OF-MANUAL
  5645.    In some documentation styles, metasyntactic variables are shown with
  5646. angle brackets, for example:
  5647.      ..., type rm <filename>
  5648. However, that is not the style that Texinfo uses.  (You can, of course,
  5649. modify the sources to TeX and the Info formatting commands to output
  5650. the `<...>' format if you wish.)
  5651. File: texi.info,  Node: file,  Next: dfn,  Prev: var,  Up: Indicating
  5652. `@file'{FILE-NAME}
  5653. ------------------
  5654.    Use the `@file' command to indicate text that is the name of a file,
  5655. buffer, or directory, or is the name of a node in Info.  You can also
  5656. use the command for file name suffixes.  Do not use `@file' for symbols
  5657. in a programming language; use `@code'.
  5658.    Currently, `@file' is equivalent to `@samp' in its effects.  For
  5659. example,
  5660.      The @file{.el} files are in
  5661.      the @file{/usr/local/emacs/lisp} directory.
  5662. produces
  5663.      The `.el' files are in the `/usr/local/emacs/lisp' directory.
  5664. File: texi.info,  Node: dfn,  Next: cite,  Prev: file,  Up: Indicating
  5665. `@dfn'{TERM}
  5666. ------------
  5667.    Use the `@dfn' command to identify the introductory or defining use
  5668. of a technical term.  Use the command only in passages whose purpose is
  5669. to introduce a term which will be used again or which the reader ought
  5670. to know.  Mere passing mention of a term for the first time does not
  5671. deserve `@dfn'.  The command generates italics in the printed manual,
  5672. and double quotation marks in the Info file.  For example:
  5673.      Getting rid of a file is called @dfn{deleting} it.
  5674. produces
  5675.      Getting rid of a file is called "deleting" it.
  5676.    As a general rule, a sentence containing the defining occurrence of a
  5677. term should be a definition of the term.  The sentence does not need to
  5678. say explicitly that it is a definition, but it should contain the
  5679. information of a definition--it should make the meaning clear.
  5680. File: texi.info,  Node: cite,  Prev: dfn,  Up: Indicating
  5681. `@cite'{REFERENCE}
  5682. ------------------
  5683.    Use the `@cite' command for the name of a book that lacks a
  5684. companion Info file. The command produces italics in the printed
  5685. manual, and quotation marks in the Info file.
  5686.    (If a book is written in Texinfo, it is better to use a cross
  5687. reference command since a reader can easily follow such a reference in
  5688. Info.  *Note `@xref': xref.)
  5689. File: texi.info,  Node: Emphasis,  Prev: Indicating,  Up: Marking Text
  5690. Emphasizing Text
  5691. ================
  5692.    Usually, Texinfo changes the font to mark words in the text
  5693. according to what category the words belong to; an example is the
  5694. `@code' command.  Most often, this is the best way to mark words.
  5695. However, sometimes you will want to emphasize text without indicating a
  5696. category.  Texinfo has two commands to do this.  Also, Texinfo has
  5697. several commands that specify the font in which TeX will typeset text.
  5698. These commands have no affect on Info and only one of them, the `@r'
  5699. command, has any regular use.
  5700. * Menu:
  5701. * emph & strong::               How to emphasize text in Texinfo.
  5702. * Smallcaps::                   How to use the small caps font.
  5703. * Fonts::                       Various font commands for printed output.
  5704. File: texi.info,  Node: emph & strong,  Next: Smallcaps,  Up: Emphasis
  5705. `@emph'{TEXT} and `@strong'{TEXT}
  5706. ---------------------------------
  5707.    The `@emph' and `@strong' commands are for emphasis; `@strong' is
  5708. stronger.  In printed output, `@emph' produces *italics* and `@strong'
  5709. produces *bold*.
  5710.    For example,
  5711.      @quotation
  5712.      @strong{Caution:} @code{rm * .[^.]*} removes @emph{all}
  5713.      files in the directory.
  5714.      @end quotation
  5715. produces:
  5716.           *Caution*: `rm * .[^.]*' removes *all*
  5717.           files in the directory.
  5718.    The `@strong' command is seldom used except to mark what is, in
  5719. effect, a typographical element, such as the word `Caution' in the
  5720. preceding example.
  5721.    In the Info file, both `@emph' and `@strong' put asterisks around
  5722. the text.
  5723.      *Caution:* Do not use `@emph' or `@strong' with the word `Note';
  5724.      Info will mistake the combination for a cross reference.  Use a
  5725.      phrase such as *Please note* or *Caution* instead.
  5726. File: texi.info,  Node: Smallcaps,  Next: Fonts,  Prev: emph & strong,  Up: Emphasis
  5727. `@sc'{TEXT}: The Small Caps Font
  5728. --------------------------------
  5729.    Use the `@sc' command to set text in the printed output in a small
  5730. caps font and set text in the Info file in upper case letters.
  5731.    Write the text between braces in lower case, like this:
  5732.      The @sc{acm} and @sc{ieee} are technical societies.
  5733. This produces:
  5734.      The ACM and IEEE are technical societies.
  5735.    TeX typesets the small caps font in a manner that prevents the
  5736. letters from `jumping out at you on the page'.  This makes small caps
  5737. text easier to read than text in all upper case.  The Info formatting
  5738. commands set all small caps text in upper case.
  5739.    If the text between the braces of an `@sc' command is upper case,
  5740. TeX typesets in full-size capitals.  Use full-size capitals sparingly.
  5741.    You may also use the small caps font for a jargon word such as ATO
  5742. (a NASA word meaning `abort to orbit').
  5743.    There are subtleties to using the small caps font with a jargon word
  5744. such as CDR, a word used in Lisp programming.  In this case, you should
  5745. use the small caps font when the word refers to the second and
  5746. subsequent elements of a list (the CDR of the list), but you should use
  5747. `@code' when the word refers to the Lisp function of the same spelling.
  5748. File: texi.info,  Node: Fonts,  Prev: Smallcaps,  Up: Emphasis
  5749. Fonts for Printing, Not Info
  5750. ----------------------------
  5751.    Texinfo provides four font commands that specify font changes in the
  5752. printed manual but have no effect in the Info file.  `@i' requests
  5753. italic font (in some versions of TeX, a slanted font is used), `@b'
  5754. requests bold face, `@t' requests the fixed-width, typewriter-style
  5755. font used by `@code', and `@r' requests a roman font, which is the
  5756. usual font in which text is printed.  All four commands apply to an
  5757. argument that follows, surrounded by braces.
  5758.    Only the `@r' command has much use: in example programs, you can use
  5759. the `@r' command to convert code comments from the fixed-width font to
  5760. a roman font.  This looks better in printed output.
  5761.    For example,
  5762.      @lisp
  5763.      (+ 2 2)    ; @r{Add two plus two.}
  5764.      @end lisp
  5765. produces
  5766.      (+ 2 2)    ; Add two plus two.
  5767.    If possible, you should avoid using the other three font commands.
  5768. If you need to use one, it probably indicates a gap in the Texinfo
  5769. language.
  5770. File: texi.info,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Marking Text,  Up: Top
  5771. Quotations and Examples
  5772. ***********************
  5773.    Quotations and examples are blocks of text consisting of one or more
  5774. whole paragraphs that are set off from the bulk of the text and treated
  5775. differently.  They are usually indented.
  5776.    In Texinfo, you always begin a quotation or example by writing an
  5777. @-command at the beginning of a line by itself, and end it by writing
  5778. an `@end' command that is also at the beginning of a line by itself.
  5779. For instance, you begin an example by writing `@example' by itself at
  5780. the beginning of a line and end the example by writing `@end example'
  5781. on a line by itself, at the beginning of that line.
  5782. * Menu:
  5783. * Block Enclosing Commands::    Use different constructs for
  5784.                                   different purposes.
  5785. * quotation::                   How to write a quotation.
  5786. * example::                     How to write an example in a fixed-width font.
  5787. * noindent::                    How to prevent paragraph indentation.
  5788. * Lisp Example::                How to illustrate Lisp code.
  5789. * smallexample & smalllisp::    Forms for the `@smallbook' option.
  5790. * display::                     How to write an example in the current font.
  5791. * format::                      How to write an example that does not narrow
  5792.                                   the margins.
  5793. * exdent::                      How to undo the indentation of a line.
  5794. * flushleft & flushright::      How to push text flushleft or flushright.
  5795. * cartouche::                   How to draw cartouches around examples.
  5796. File: texi.info,  Node: Block Enclosing Commands,  Next: quotation,  Up: Quotations and Examples
  5797. The Block Enclosing Commands
  5798. ============================
  5799.    Here are commands for quotations and examples:
  5800. `@quotation'
  5801.      Indicate text that is quoted. The text is filled, indented, and
  5802.      printed in a roman font by default.
  5803. `@example'
  5804.      Illustrate code, commands, and the like. The text is printed in a
  5805.      fixed-width font, and indented but not filled.
  5806. `@lisp'
  5807.      Illustrate Lisp code. The text is printed in a fixed-width font,
  5808.      and indented but not filled.
  5809. `@smallexample'
  5810.      Illustrate code, commands, and the like.  Similar to `@example',
  5811.      except that in TeX this command typesets text in a smaller font
  5812.      for the smaller `@smallbook' format than for the 8.5 by 11 inch
  5813.      format.
  5814. `@smalllisp'
  5815.      Illustrate Lisp code.  Similar to `@lisp', except that in TeX this
  5816.      command typesets text in a smaller font for the smaller
  5817.      `@smallbook' format than for the 8.5 by 11 inch format.
  5818. `@display'
  5819.      Display illustrative text.  The text is indented but not filled,
  5820.      and no font is specified (so, by default, the font is roman).
  5821. `@format'
  5822.      Print illustrative text.  The text is not indented and not filled
  5823.      and no font is specified (so, by default, the font is roman).
  5824.    The `@exdent' command is used within the above constructs to undo
  5825. the indentation of a line.
  5826.    The `@flushleft' and `@flushright' commands are used to line up the
  5827. left or right margins of unfilled text.
  5828.    The `@noindent' command may be used after one of the above
  5829. constructs to prevent the following text from being indented as a new
  5830. paragraph.
  5831.    You can use the `@cartouche' command within one of the above
  5832. constructs to highlight the example or quotation by drawing a box with
  5833. rounded corners around it.  (The `@cartouche' command affects only the
  5834. printed manual; it has no effect in the Info file; see *Note Drawing
  5835. Cartouches Around Examples: cartouche.)
  5836. File: texi.info,  Node: quotation,  Next: example,  Prev: Block Enclosing Commands,  Up: Quotations and Examples
  5837. `@quotation'
  5838. ============
  5839.    The text of a quotation is processed normally except that:
  5840.    * the margins are closer to the center of the page, so the whole of
  5841.      the quotation is indented;
  5842.    * the first lines of paragraphs are indented no more than other
  5843.      lines;
  5844.    * in the printed output, interparagraph spacing is reduced.
  5845.      This is an example of text written between an `@quotation' command
  5846.      and an `@end quotation' command.  An `@quotation' command is most
  5847.      often used to indicate text that is excerpted from another (real
  5848.      or hypothetical) printed work.
  5849.    Write an `@quotation' command as text on a line by itself.  This
  5850. line will disappear from the output.  Mark the end of the quotation
  5851. with a line beginning with and containing only `@end quotation'.  The
  5852. `@end quotation' line will likewise disappear from the output.  Thus,
  5853. the following,
  5854.      @quotation
  5855.      This is
  5856.      a foo.
  5857.      @end quotation
  5858. produces
  5859.      This is a foo.
  5860. File: texi.info,  Node: example,  Next: noindent,  Prev: quotation,  Up: Quotations and Examples
  5861. `@example'
  5862. ==========
  5863.    The `@example' command is used to indicate an example that is not
  5864. part of the running text, such as computer input or output.
  5865.      This is an example of text written between an
  5866.      `@example' command
  5867.      and an `@end example' command.
  5868.      The text is indented but not filled.
  5869.      
  5870.      In the printed manual, the text is typeset in a
  5871.      fixed-width font, and extra spaces and blank lines are
  5872.      significant.  In the Info file, an analogous result is
  5873.      obtained by indenting each line with five spaces.
  5874.    Write an `@example' command at the beginning of a line by itself.
  5875. This line will disappear from the output.  Mark the end of the example
  5876. with an `@end example' command, also written at the beginning of a line
  5877. by itself.  The `@end example' will disappear from the output.
  5878.    For example,
  5879.      @example
  5880.      mv foo bar
  5881.      @end example
  5882. produces
  5883.      mv foo bar
  5884.    Since the lines containing `@example' and `@end example' will
  5885. disappear, you should put a blank line before the `@example' and
  5886. another blank line after the `@end example'.  (Remember that blank
  5887. lines between the beginning `@example' and the ending `@end example'
  5888. will appear in the output.)
  5889.      *Caution:* Do not use tabs in the lines of an example (or anywhere
  5890.      else in Texinfo, for that matter)!  TeX treats tabs as single
  5891.      spaces, and that is not what they look like.  This is a problem
  5892.      with TeX.  (If necessary, in Emacs, you can use `M-x untabify' to
  5893.      convert tabs in a region to multiple spaces.)
  5894.    Examples are often, logically speaking, "in the middle" of a
  5895. paragraph, and the text continues after an example should not be
  5896. indented.  The `@noindent' command prevents a piece of text from being
  5897. indented as if it were a new paragraph.  (*Note noindent::.)
  5898.    (The `@code' command is used for examples of code that are embedded
  5899. within sentences, not set off from preceding and following text.  *Note
  5900. `@code': code.)
  5901. File: texi.info,  Node: noindent,  Next: Lisp Example,  Prev: example,  Up: Quotations and Examples
  5902. `@noindent'
  5903. ===========
  5904.    An example or other inclusion can break a paragraph into segments.
  5905. Ordinarily, the formatters indent text that follows an example as a new
  5906. paragraph.  However, you can prevent this by writing `@noindent' at the
  5907. beginning of a line by itself preceding the continuation text.
  5908.    For example:
  5909.      @example
  5910.      This is an example
  5911.      @end example
  5912.      
  5913.      @noindent
  5914.      This line is not indented.  As you can see, the
  5915.      beginning of the line is fully flush left with the line
  5916.      that follows after it.  (This whole example is between
  5917.      @code{@@display} and @code{@@end display}.)
  5918. produces
  5919.           This is an example
  5920.      
  5921.      
  5922.      This line is not indented.  As you can see, the
  5923.      beginning of the line is fully flush left with the line
  5924.      that follows after it.  (This whole example is between
  5925.      `@display' and `@end display'.)
  5926.    To adjust the number of blank lines properly in the Info file output,
  5927. remember that the line containing `@noindent' does not generate a blank
  5928. line, and neither does the `@end example' line.
  5929.    In the Texinfo source file for this manual, each line that says
  5930. `produces' is preceded by a line containing `@noindent'.
  5931.    Do not put braces after an `@noindent' command; they are not
  5932. necessary, since `@noindent' is a command used outside of paragraphs
  5933. (*note Command Syntax::.).
  5934. File: texi.info,  Node: Lisp Example,  Next: smallexample & smalllisp,  Prev: noindent,  Up: Quotations and Examples
  5935. `@lisp'
  5936. =======
  5937.    The `@lisp' command is used for Lisp code.  It is synonymous with
  5938. the `@example' command.
  5939.      This is an example of text written between an
  5940.      `@lisp' command and an `@end lisp' command.
  5941.    Use `@lisp' instead of `@example' so as to preserve information
  5942. regarding the nature of the example.  This is useful, for example, if
  5943. you write a function that evaluates only and all the Lisp code in a
  5944. Texinfo file.  Then you can use the Texinfo file as a Lisp library.(1)
  5945.    Mark the end of `@lisp' with `@end lisp' on a line by itself.
  5946.    ---------- Footnotes ----------
  5947.    (1)  It would be straightforward to extend Texinfo to work in a
  5948. similar fashion for C, FORTRAN, or other languages.
  5949. File: texi.info,  Node: smallexample & smalllisp,  Next: display,  Prev: Lisp Example,  Up: Quotations and Examples
  5950. `@smallexample' and `@smalllisp'
  5951. ================================
  5952.    In addition to the regular `@example' and `@lisp' commands, Texinfo
  5953. has two other "example-style" commands.  These are the `@smallexample'
  5954. and `@smalllisp' commands.  Both these commands are designed for use
  5955. with the `@smallbook' command that causes TeX to produce a printed
  5956. manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
  5957. inch format.
  5958.    In TeX, the `@smallexample' and `@smalllisp' commands typeset text
  5959. in a smaller font for the smaller `@smallbook' format than for the 8.5
  5960. by 11 inch format.  Consequently, many examples containing long lines
  5961. fit in a narrower, `@smallbook' page without needing to be shortened.
  5962. Both commands typeset in the normal font size when you format for the
  5963. 8.5 by 11 inch size; indeed, in this situation, the `@smallexample' and
  5964. `@smalllisp' commands are defined to be the `@example' and `@lisp'
  5965. commands.
  5966.    In Info, the `@smallexample' and `@smalllisp' commands are
  5967. equivalent to the `@example' and `@lisp' commands, and work exactly the
  5968. same.
  5969.    Mark the end of `@smallexample' or `@smalllisp' with `@end
  5970. smallexample' or `@end smalllisp', respectively.
  5971.      This is an example of text written between `@smallexample' and
  5972.      `@end smallexample'.  In Info and in an 8.5 by 11 inch manual,
  5973.      this text appears in its normal size; but in a 7 by 9.25 inch manual,
  5974.      this text appears in a smaller font.
  5975.    The `@smallexample' and `@smalllisp' commands make it easier to
  5976. prepare smaller format manuals without forcing you to edit examples by
  5977. hand to fit them onto narrower pages.
  5978.    As a general rule, a printed document looks better if you write all
  5979. the examples in a chapter consistently in `@example' or in
  5980. `@smallexample'.  Only occasionally should you mix the two formats.
  5981.    *Note Printing "Small" Books: smallbook, for more information about
  5982. the `@smallbook' command.
  5983. File: texi.info,  Node: display,  Next: format,  Prev: smallexample & smalllisp,  Up: Quotations and Examples
  5984. `@display'
  5985. ==========
  5986.    The `@display' command begins a kind of example.  It is like the
  5987. `@example' command except that, in a printed manual, `@display' does
  5988. not select the fixed-width font.  In fact, it does not specify the font
  5989. at all, so that the text appears in the same font it would have
  5990. appeared in without the `@display' command.
  5991.      This is an example of text written between an `@display' command
  5992.      and an `@end display' command.  The `@display' command
  5993.      indents the text, but does not fill it.
  5994. File: texi.info,  Node: format,  Next: exdent,  Prev: display,  Up: Quotations and Examples
  5995. `@format'
  5996. =========
  5997.    The `@format' command is similar to `@example' except that, in the
  5998. printed manual, `@format' does not select the fixed-width font and does
  5999. not narrow the margins.
  6000. This is an example of text written between an `@format' command
  6001. and an `@end format' command.  As you can see
  6002. from this example,
  6003. the `@format' command does not fill the text.
  6004. File: texi.info,  Node: exdent,  Next: flushleft & flushright,  Prev: format,  Up: Quotations and Examples
  6005. `@exdent': Undoing a Line's Indentation
  6006. =======================================
  6007.    The `@exdent' command removes any indentation a line might have.
  6008. The command is written at the beginning of a line and applies only to
  6009. the text that follows the command that is on the same line.  Do not use
  6010. braces around the text.  In a printed manual, the text on an `@exdent'
  6011. line is printed in the roman font.
  6012.    `@exdent' is usually used within examples.  Thus,
  6013.      @example
  6014.      This line follows an @@example command.
  6015.      @exdent This line is exdented.
  6016.      This line follows the exdented line.
  6017.      The @@end example comes on the next line.
  6018.      @end group
  6019. produces
  6020.      This line follows an @example command.
  6021. This line is exdented.
  6022.      This line follows the exdented line.
  6023.      The @end example comes on the next line.
  6024.    In practice, the `@exdent' command is rarely used.  Usually, you
  6025. un-indent text by ending the example and returning the page to its
  6026. normal width.
  6027. File: texi.info,  Node: flushleft & flushright,  Next: cartouche,  Prev: exdent,  Up: Quotations and Examples
  6028. `@flushleft' and `@flushright'
  6029. ==============================
  6030.    The `@flushleft' and `@flushright' commands line up the ends of
  6031. lines on the left and right margins of a page, but do not fill the
  6032. text.  The commands are written on lines of their own, without braces.
  6033. The `@flushleft' and `@flushright' commands are ended by `@end
  6034. flushleft' and `@end flushright' commands on lines of their own.
  6035.    For example,
  6036.      @flushleft
  6037.      This text is
  6038.      written flushleft.
  6039.      @end flushleft
  6040. produces
  6041.      This text is
  6042.      written flushleft.
  6043.    Flushright produces the type of indentation often used in the return
  6044. address of letters.
  6045. For example,
  6046.      @flushright
  6047.      Here is an example of text written
  6048.      flushright.  The @code{@flushright} command
  6049.      right justifies every line but leaves the
  6050.      left end ragged.
  6051.      @end flushright
  6052. produces
  6053.                                      Here is an example of text written
  6054.                                  flushright.  The `@flushright' command
  6055.                               right justifies every line but leaves the
  6056.                                                        left end ragged.
  6057. File: texi.info,  Node: cartouche,  Prev: flushleft & flushright,  Up: Quotations and Examples
  6058. Drawing Cartouches Around Examples
  6059. ==================================
  6060.    In a printed manual, the `@cartouche' command draws a box with
  6061. rounded corners around its contents.  You can use this command to
  6062. further highlight an example or quotation.  For instance, you could
  6063. write a manual in which one type of example is surrounded by a cartouche
  6064. for emphasis.
  6065.    The `@cartouche' command affects only the printed manual; it has no
  6066. effect in the Info file.
  6067.    For example,
  6068.      @example
  6069.      @cartouche
  6070.      % pwd
  6071.      /usr/local/lib/emacs/info
  6072.      @end cartouche
  6073.      @end example
  6074. surrounds the two-line example with a box with rounded corners, in the
  6075. printed manual.
  6076. File: texi.info,  Node: Lists and Tables,  Next: Indices,  Prev: Quotations and Examples,  Up: Top
  6077. Making Lists and Tables
  6078. ***********************
  6079.    Texinfo has several ways of making lists and two-column tables.
  6080. Lists can be bulleted or numbered, while two-column tables can
  6081. highlight the items in the first column.
  6082. * Menu:
  6083. * Introducing Lists::           Texinfo formats lists for you.
  6084. * itemize::                     How to construct a simple list.
  6085. * enumerate::                   How to construct a numbered list.
  6086. * Two-column Tables::           How to construct a two-column table.
  6087. File: texi.info,  Node: Introducing Lists,  Next: itemize,  Up: Lists and Tables
  6088. Introducing Lists
  6089. =================
  6090.    Texinfo automatically indents the text in lists or tables, and
  6091. numbers an enumerated list.  This last feature is useful if you modify
  6092. the list, since you do not need to renumber it yourself.
  6093.    Numbered lists and tables begin with the appropriate @-command at the
  6094. beginning of a line, and end with the corresponding `@end' command on a
  6095. line by itself.  The table and itemized-list commands also require that
  6096. you write formatting information on the same line as the beginning
  6097. @-command.
  6098.    Begin an enumerated list, for example, with an `@enumerate' command
  6099. and end the list with an `@end enumerate' command.  Begin an itemized
  6100. list with an `@itemize' command, followed on the same line by a
  6101. formatting command such as `@bullet', and end the list with an `@end
  6102. itemize' command.
  6103.    Precede each element of a list with an `@item' or `@itemx' command.
  6104. Here is an itemized list of the different kinds of table and lists:
  6105.    * Itemized lists with and without bullets.
  6106.    * Enumerated lists, using numbers or letters.
  6107.    * Two-column tables with highlighting.
  6108. Here is an enumerated list with the same items:
  6109.   1. Itemized lists with and without bullets.
  6110.   2. Enumerated lists, using numbers or letters.
  6111.   3. Two-column tables with highlighting.
  6112. And here is a two-column table with the same items and their @-commands:
  6113. `@itemize'
  6114.      Itemized lists with and without bullets.
  6115. `@enumerate'
  6116.      Enumerated lists, using numbers or letters.
  6117. `@table'
  6118. `@ftable'
  6119. `@vtable'
  6120.      Two-column tables with highlighting.
  6121. File: texi.info,  Node: itemize,  Next: enumerate,  Prev: Introducing Lists,  Up: Lists and Tables
  6122. Making an Itemized List
  6123. =======================
  6124.    The `@itemize' command produces sequences of indented paragraphs,
  6125. with a bullet or other mark inside the left margin at the beginning of
  6126. each paragraph for which such a mark is desired.
  6127.    Begin an itemized list by writing `@itemize' at the beginning of a
  6128. line.  Follow the command, on the same line, with a character or a
  6129. Texinfo command that generates a mark.  Usually, you will write
  6130. `@bullet' after `@itemize', but you can use `@minus', or any character
  6131. or any special symbol that results in a single character in the Info
  6132. file.  (When you write `@bullet' or `@minus' after an `@itemize'
  6133. command, you may omit the `{}'.)
  6134.    Write the text of the indented paragraphs themselves after the
  6135. `@itemize', up to another line that says `@end itemize'.
  6136.    Before each paragraph for which a mark in the margin is desired,
  6137. write a line that says just `@item'.  Do not write any other text on
  6138. this line.
  6139.    Usually, you should put a blank line before an `@item'.  This puts a
  6140. blank line in the Info file. (TeX inserts the proper interline
  6141. whitespace in either case.)  Except when the entries are very brief,
  6142. these blank lines make the list look better.
  6143.    Here is an example of the use of `@itemize', followed by the output
  6144. it produces.  Note that `@bullet' produces an `*' in Info and a round
  6145. dot in TeX.
  6146.      @itemize @bullet
  6147.      @item
  6148.      Some text for foo.
  6149.      
  6150.      @item
  6151.      Some text
  6152.      for bar.
  6153.      @end itemize
  6154. This produces:
  6155.         * Some text for foo.
  6156.         * Some text for bar.
  6157.    Itemized lists may be embedded within other itemized lists.  Here is
  6158. a list marked with dashes embedded in a list marked with bullets:
  6159.      @itemize @bullet
  6160.      @item
  6161.      First item.
  6162.      
  6163.      @itemize @minus
  6164.      @item
  6165.      Inner item.
  6166.      
  6167.      @item
  6168.      Second inner item.
  6169.      @end itemize
  6170.      
  6171.      @item
  6172.      Second outer item.
  6173.      @end itemize
  6174. This produces:
  6175.         * First item.
  6176.              - Inner item.
  6177.              - Second inner item.
  6178.         * Second outer item.
  6179. File: texi.info,  Node: enumerate,  Next: Two-column Tables,  Prev: itemize,  Up: Lists and Tables
  6180. Making a Numbered or Lettered List
  6181. ==================================
  6182.    `@enumerate' is like `@itemize' except that the marks in the left
  6183. margin contain successive integers or letters.  (*Note `@itemize':
  6184. itemize.)
  6185.    Write the `@enumerate' command at the beginning of a line.  The
  6186. command does not require an argument, but accepts either a number or a
  6187. letter as an option.  Without an argument, `@enumerate' starts the list
  6188. with the number 1.  With a numeric argument, such as 3, the command
  6189. starts the list with that number.  With an upper or lower case letter,
  6190. such as `a' or `A', the command starts the list with that letter.
  6191.    Write the text of the enumerated list in the same way you write an
  6192. itemized list: put `@item' on a line of its own before the start of
  6193. each paragraph that you want enumerated.  Do not write any other text on
  6194. the line beginning with `@item'.
  6195.    You should put a blank line between entries in the list.  This
  6196. generally makes it easier to read the Info file.
  6197.    Here is an example of `@enumerate' without an argument:
  6198.      @enumerate
  6199.      @item
  6200.      Underlying causes.
  6201.      
  6202.      @item
  6203.      Proximate causes.
  6204.      @end enumerate
  6205. This produces:
  6206.   1. Underlying causes.
  6207.   2. Proximate causes.
  6208.    Here is an example with an argument of `3':
  6209.      @enumerate 3
  6210.      @item
  6211.      Predisposing causes.
  6212.      
  6213.      @item
  6214.      Precipitating causes.
  6215.      
  6216.      @item
  6217.      Perpetuating causes.
  6218.      @end enumerate
  6219. This produces:
  6220.   3. Predisposing causes.
  6221.   4. Precipitating causes.
  6222.   5. Perpetuating causes.
  6223.    Here is a brief summary of the alternatives.  The summary is
  6224. constructed using `@enumerate' with an argument of `a'.
  6225.   a. `@enumerate'
  6226.      Without an argument, produce a numbered list, starting with the
  6227.      number 1.
  6228.   b. `@enumerate POSITIVE-INTEGER'
  6229.      With a (positive) numeric argument, start a numbered list with that
  6230.      number.  You can use this to continue a list that you interrupted
  6231.      with other text.
  6232.   c. `@enumerate UPPER-CASE-LETTER'
  6233.      With an upper case letter as argument, start a list in which each
  6234.      item is marked by a letter, beginning with that upper case letter.
  6235.   d. `@enumerate LOWER-CASE-LETTER'
  6236.      With a lower case letter as argument, start a list in which each
  6237.      item is marked by a letter, beginning with that lower case letter.
  6238.    You can also nest enumerated lists, as in an outline.
  6239. File: texi.info,  Node: Two-column Tables,  Prev: enumerate,  Up: Lists and Tables
  6240. Making a Two-column Table
  6241. =========================
  6242.    `@table' is similar to `@itemize', but the command allows you to
  6243. specify a name or heading line for each item.  (*Note `@itemize':
  6244. itemize.)  The `@table' command is used to produce two-column tables,
  6245. and is especially useful for glossaries and explanatory exhibits.
  6246. * Menu:
  6247. * table::                       How to construct a two-column table.
  6248. * ftable vtable::               How to construct a two-column table
  6249.                                   with automatic indexing.
  6250. * itemx::                       How to put more entries in the first column.
  6251. File: texi.info,  Node: table,  Next: ftable vtable,  Up: Two-column Tables
  6252. Using the `@table' Command
  6253. --------------------------
  6254.    Use the `@table' command to produce two-column tables.
  6255.    Write the `@table' command at the beginning of a line and follow it
  6256. on the same line with an argument that is a Texinfo command such as
  6257. `@code', `@samp', `@var', or `@kbd'.  Although these commands are
  6258. usually followed by arguments in braces, in this case you use the
  6259. command name without an argument because `@item' will supply the
  6260. argument.  This command will be applied to the text that goes into the
  6261. first column of each item and determines how it will be highlighted.
  6262. For example, `@samp' will cause the text in the first column to be
  6263. highlighted with an `@samp' command.
  6264.    You may also choose to use the `@asis' command as an argument to
  6265. `@table'.  `@asis' is a command that does nothing; if you use this
  6266. command after `@table', TeX and the Info formatting commands output the
  6267. first column entries without added highlighting (`as is').
  6268.    (The `@table' command may work with other commands besides those
  6269. listed here.  However, you can only use commands that normally take
  6270. arguments in braces.)
  6271.    Begin each table entry with an `@item' command at the beginning of a
  6272. line.  Write the first column text on the same line as the `@item'
  6273. command.  Write the second column text on the line following the
  6274. `@item' line and on subsequent lines.  (You do not need to type
  6275. anything for an empty second column entry.)  You may write as many
  6276. lines of supporting text as you wish, even several paragraphs.  But
  6277. only text on the same line as the `@item' will be placed in the first
  6278. column.
  6279.    Normally, you should put a blank line before an `@item' line.  This
  6280. puts a blank like in the Info file.  Except when the entries are very
  6281. brief, a blank line looks better.
  6282.    The following table, for example, highlights the text in the first
  6283. column with an `@samp' command:
  6284.      @table @samp
  6285.      @item foo
  6286.      This is the text for
  6287.      @samp{foo}.
  6288.      
  6289.      @item bar
  6290.      Text for @samp{bar}.
  6291.      @end table
  6292. This produces:
  6293. `foo'
  6294.      This is the text for `foo'.
  6295. `bar'
  6296.      Text for `bar'.
  6297.    If you want to list two or more named items with a single block of
  6298. text, use the `@itemx' command.  (*Note `@itemx': itemx.)
  6299. File: texi.info,  Node: ftable vtable,  Next: itemx,  Prev: table,  Up: Two-column Tables
  6300. `@ftable' and `@vtable'
  6301. -----------------------
  6302.    The `@ftable' and `@vtable' commands are the same as the `@table'
  6303. command except that `@ftable' automatically enters each of the items in
  6304. the first column of the table into the index of functions and `@vtable'
  6305. automatically enters each of the items in the first column of the table
  6306. into the index of variables.  This simplifies the task of creating
  6307. indices.  Only the items on the same line as the `@item' commands are
  6308. indexed, and they are indexed in exactly the form that they appear on
  6309. that line.  *Note Creating Indices: Indices, for more information about
  6310. indices.
  6311.    Begin a two-column table using `@ftable' or `@vtable' by writing the
  6312. @-command at the beginning of a line, followed on the same line by an
  6313. argument that is a Texinfo command such as `@code', exactly as you
  6314. would for an `@table' command; and end the table with an `@end ftable'
  6315. or `@end vtable' command on a line by itself.
  6316. File: texi.info,  Node: itemx,  Prev: ftable vtable,  Up: Two-column Tables
  6317. `@itemx'
  6318. --------
  6319.    Use the `@itemx' command inside a table when you have two or more
  6320. first column entries for the same item, each of which should appear on
  6321. a line of its own.  Use `@itemx' for all but the first entry.  The
  6322. `@itemx' command works exactly like `@item' except that it does not
  6323. generate extra vertical space above the first column text.
  6324.    For example,
  6325.      @table @code
  6326.      @item upcase
  6327.      @itemx downcase
  6328.      These two functions accept a character or a string as
  6329.      argument, and return the corresponding upper case (lower
  6330.      case) character or string.
  6331.      @end table
  6332. This produces:
  6333. `upcase'
  6334. `downcase'
  6335.      These two functions accept a character or a string as argument,
  6336.      and return the corresponding upper case (lower case) character or
  6337.      string.
  6338. (Note also that this example illustrates multi-line supporting text in
  6339. a two-column table.)
  6340. File: texi.info,  Node: Indices,  Next: Insertions,  Prev: Lists and Tables,  Up: Top
  6341. Creating Indices
  6342. ****************
  6343.    Using Texinfo, you can generate indices without having to sort and
  6344. collate entries manually.  In an index, the entries are listed in
  6345. alphabetical order, together with information on how to find the
  6346. discussion of each entry.  In a printed manual, this information
  6347. consists of page numbers.  In an Info file, this information is a menu
  6348. entry leading to the first node referenced.
  6349.    Texinfo provides several predefined kinds of index: an index for
  6350. functions, an index for variables, an index for concepts, and so on.
  6351. You can combine indices or use them for other than their canonical
  6352. purpose.  If you wish, you can define your own indices.
  6353. * Menu:
  6354. * Index Entries::               Choose different words for index entries.
  6355. * Predefined Indices::          Use different indices for different kinds
  6356.                                   of entry.
  6357. * Indexing Commands::           How to make an index entry.
  6358. * Combining Indices::           How to combine indices.
  6359. * New Indices::                 How to define your own indices.
  6360. File: texi.info,  Node: Index Entries,  Next: Predefined Indices,  Up: Indices
  6361. Making Index Entries
  6362. ====================
  6363.    When you are making index entries, it is good practice to think of
  6364. the different ways people may look for something.  Different people *do
  6365. not* think of the same words when they look something up.  A helpful
  6366. index will have items indexed under all the different words that people
  6367. may use.  For example, one reader may think it obvious that the
  6368. two-letter names for indices should be listed under "Indices,
  6369. two-letter names", since the word "Index" is the general concept.  But
  6370. another reader may remember the specific concept of two-letter names
  6371. and search for the entry listed as "Two letter names for indices".  A
  6372. good index will have both entries and will help both readers.
  6373.    Like typesetting, the construction of an index is a highly skilled,
  6374. professional art, the subtleties of which are not appreciated until you
  6375. need to do it yourself.
  6376.    *Note Printing Indices & Menus::, for information about printing an
  6377. index at the end of a book or creating an index menu in an Info file.
  6378. File: texi.info,  Node: Predefined Indices,  Next: Indexing Commands,  Prev: Index Entries,  Up: Indices
  6379. Predefined Indices
  6380. ==================
  6381.    Texinfo provides six predefined indices:
  6382.    * A "concept index" listing concepts that are discussed.
  6383.    * A "function index" listing functions (such as entry points of
  6384.      libraries).
  6385.    * A "variables index" listing variables (such as global variables of
  6386.      libraries).
  6387.    * A "keystroke index" listing keyboard commands.
  6388.    * A "program index" listing names of programs.
  6389.    * A "data type index" listing data types (such as structures defined
  6390.      in header files).
  6391. Not every manual needs all of these, and most manuals use two or three
  6392. of them.  This manual has two indices: a concept index and an @-command
  6393. index (that is actually the function index but is called a command
  6394. index in the chapter heading).  Two or more indices can be combined
  6395. into one using the `@synindex' or `@syncodeindex' commands.  *Note
  6396. Combining Indices::.
  6397. File: texi.info,  Node: Indexing Commands,  Next: Combining Indices,  Prev: Predefined Indices,  Up: Indices
  6398. Defining the Entries of an Index
  6399. ================================
  6400.    The data to make an index come from many individual indexing commands
  6401. scattered throughout the Texinfo source file.  Each command says to add
  6402. one entry to a particular index; after formatting, the index will give
  6403. the current page number or node name as the reference.
  6404.    An index entry consists of an indexing command at the beginning of a
  6405. line followed, on the rest of the line, by the entry.
  6406.    For example, this section begins with the following five entries for
  6407. the concept index:
  6408.      @cindex Defining indexing entries
  6409.      @cindex Index entries
  6410.      @cindex Entries for an index
  6411.      @cindex Specifying index entries
  6412.      @cindex Creating index entries
  6413.    Each predefined index has its own indexing command--`@cindex' for
  6414. the concept index, `@findex' for the function index, and so on.
  6415.    The usual convention is to capitalize the first word of each index
  6416. entry, unless that word is the name of a function, variable, or other
  6417. such entity that should not be capitalized.  Thus, if you are
  6418. documenting Emacs Lisp, you should usually capitalize entries in the
  6419. concept index, but not those in the function index.  However, if your
  6420. concept index entries are consistently short (one or two words each) it
  6421. may look better for each regular entry to start with a lower case
  6422. letter.  Whichever convention you adapt, please be consistent!
  6423.    By default, entries for a concept index are printed in a small roman
  6424. font and entries for the other indices are printed in a small `@code'
  6425. font.  You may change the way part of an entry is printed with the
  6426. usual Texinfo commands, such as `@file' for file names and `@emph' for
  6427. emphasis (*note Marking Text::.).
  6428.    The six indexing commands for predefined indices are:
  6429. `@cindex CONCEPT'
  6430.      Make an entry in the concept index for CONCEPT.
  6431. `@findex FUNCTION'
  6432.      Make an entry in the function index for FUNCTION.
  6433. `@vindex VARIABLE'
  6434.      Make an entry in the variable index for VARIABLE.
  6435. `@kindex KEYSTROKE'
  6436.      Make an entry in the key index for KEYSTROKE.
  6437. `@pindex PROGRAM'
  6438.      Make an entry in the program index for PROGRAM.
  6439. `@tindex DATA TYPE'
  6440.      Make an entry in the data type index for DATA TYPE.
  6441.      *Caution:* Do not use a colon in an index entry.  In Info, a colon
  6442.      separates the menu entry name from the node name.  An extra colon
  6443.      confuses Info.  *Note The Parts of a Menu: Menu Parts, for more
  6444.      information about the structure of a menu entry.
  6445.    If you write several identical index entries in different places in a
  6446. Texinfo file, the index in the printed manual will list all the pages to
  6447. which those entries refer.  However, the index in the Info file will
  6448. list *only* the node that references the *first* of those index
  6449. entries.  Therefore, it is best to write indices in which each entry
  6450. refers to only one place in the Texinfo file.  Fortunately, this
  6451. constraint is a feature rather than a loss since it means that the index
  6452. will be easy to use.  Otherwise, you could create an index that lists
  6453. several pages for one entry and your reader would not know to which page
  6454. to turn.  If you have two identical entries for one topic, change the
  6455. topics slightly, or qualify them to indicate the difference.
  6456.    You are not actually required to use the predefined indices for their
  6457. canonical purposes.  For example, suppose you wish to index some C
  6458. preprocessor macros.  You could put them in the function index along
  6459. with actual functions, just by writing `@findex' commands for them;
  6460. then, when you print the "Function Index" as an unnumbered chapter, you
  6461. could give it the title `Function and Macro Index' and all will be
  6462. consistent for the reader.  Or you could put the macros in with the
  6463. data types by writing `@tindex' commands for them, and give that index
  6464. a suitable title so the reader will understand.  (*Note Printing
  6465. Indices & Menus::.)
  6466. File: texi.info,  Node: Combining Indices,  Next: New Indices,  Prev: Indexing Commands,  Up: Indices
  6467. Combining Indices
  6468. =================
  6469.    Sometimes you will want to combine two disparate indices such as
  6470. functions and concepts, perhaps because you have few enough of one of
  6471. them that a separate index for them would look silly.
  6472.    You could put functions into the concept index by writing `@cindex'
  6473. commands for them instead of `@findex' commands, and produce a
  6474. consistent manual by printing the concept index with the title
  6475. `Function and Concept Index' and not printing the `Function Index' at
  6476. all; but this is not a robust procedure.  It works only if your
  6477. document is never included as part of another document that is designed
  6478. to have a separate function index; if your document were to be included
  6479. with such a document, the functions from your document and those from
  6480. the other would not end up together.  Also, to make your function names
  6481. appear in the right font in the concept index, you would need to
  6482. enclose every one of them between the braces of `@code'.
  6483. * Menu:
  6484. * syncodeindex::                How to merge two indices, using `@code'
  6485.                                   font for the merged-from index.
  6486. * synindex::                    How to merge two indices, using the
  6487.                                   default font of the merged-to index.
  6488. File: texi.info,  Node: syncodeindex,  Next: synindex,  Up: Combining Indices
  6489. `@syncodeindex'
  6490. ...............
  6491.    When you want to combine functions and concepts into one index, you
  6492. should index the functions with `@findex' and index the concepts with
  6493. `@cindex', and use the `@syncodeindex' command to redirect the function
  6494. index entries into the concept index.
  6495.    The `@syncodeindex' command takes two arguments; they are the name
  6496. of the index to redirect, and the name of the index to redirect it to.
  6497. The template looks like this:
  6498.      @syncodeindex FROM TO
  6499.    For this purpose, the indices are given two-letter names:
  6500.      concept index
  6501.      function index
  6502.      variable index
  6503.      key index
  6504.      program index
  6505.      data type index
  6506.    Write an `@syncodeindex' command before or shortly after the
  6507. end-of-header line at the beginning of a Texinfo file.  For example, to
  6508. merge a function index with a concept index, write the following:
  6509.      @syncodeindex fn cp
  6510. This will cause all entries designated for the function index to merge
  6511. in with the concept index instead.
  6512.    To merge both a variables index and a function index into a concept
  6513. index, write the following:
  6514.      @syncodeindex vr cp
  6515.      @syncodeindex fn cp
  6516.    The `@syncodeindex' command puts all the entries from the `from'
  6517. index (the redirected index) into the `@code' font, overriding whatever
  6518. default font is used by the index to which the entries are now
  6519. directed.  This way, if you direct function names from a function index
  6520. into a concept index, all the function names are printed in the `@code'
  6521. font as you would expect.
  6522. File: texi.info,  Node: synindex,  Prev: syncodeindex,  Up: Combining Indices
  6523. `@synindex'
  6524. ...........
  6525.    The `@synindex' command is nearly the same as the `@syncodeindex'
  6526. command, except that it does not put the `from' index  entries into the
  6527. `@code' font; rather it puts them in the roman font.  Thus, you use
  6528. `@synindex' when you merge a concept index into a function index.
  6529.    *Note Printing Indices & Menus::, for information about printing an
  6530. index at the end of a book or creating an index menu in an Info file.
  6531. File: texi.info,  Node: New Indices,  Prev: Combining Indices,  Up: Indices
  6532. Defining New Indices
  6533. ====================
  6534.    In addition to the predefined indices, you may use the `@defindex'
  6535. and `@defcodeindex' commands to define new indices.  These commands
  6536. create new indexing @-commands with which you mark index entries.  The
  6537. `@defindex 'command is used like this:
  6538.      @defindex NAME
  6539.    The name of an index should be a two letter word, such as `au'.  For
  6540. example:
  6541.      @defindex au
  6542.    This defines a new index, called the `au' index.  At the same time,
  6543. it creates a new indexing command, `@auindex', that you can use to make
  6544. index entries.  Use the new indexing command just as you would use a
  6545. predefined indexing command.
  6546.    For example, here is a section heading followed by a concept index
  6547. entry and two `au' index entries.
  6548.      @section Cognitive Semantics
  6549.      @cindex kinesthetic image schemas
  6550.      @auindex Johnson, Mark
  6551.      @auindex Lakoff, George
  6552. (Evidently, `au' serves here as an abbreviation for "author".) Texinfo
  6553. constructs the new indexing command by concatenating the name of the
  6554. index with `index'; thus, defining an `au' index leads to the automatic
  6555. creation of an `@auindex' command.
  6556.    Use the `@printindex' command to print the index, as you do with the
  6557. predefined indices.  For example:
  6558.      @node Author Index, Subject Index, , Top
  6559.      @unnumbered Author Index
  6560.      
  6561.      @printindex au
  6562.    The `@defcodeindex' is like the `@defindex' command, except that, in
  6563. the printed output, it prints entries in an `@code' font instead of a
  6564. roman font.  Thus, it parallels the `@findex' command rather than the
  6565. `@cindex' command.
  6566.    You should define new indices within or right after the end-of-header
  6567. line of a Texinfo file, before any `@synindex' or `@syncodeindex'
  6568. commands (*note Header::.).
  6569. File: texi.info,  Node: Insertions,  Next: Glyphs,  Prev: Indices,  Up: Top
  6570. Special Insertions
  6571. ******************
  6572.    Texinfo provides several commands for formatting dimensions, for
  6573. inserting single characters that have special meaning in Texinfo, such
  6574. as braces, and for inserting special graphic symbols that do not
  6575. correspond to characters, such as dots and bullets.
  6576. * Menu:
  6577. * Braces Atsigns Periods::      How to insert braces, `@' and periods.
  6578. * dmn::                         How to format a dimension.
  6579. * Dots Bullets::                How to insert dots and bullets.
  6580. * TeX and copyright::           How to insert the TeX logo
  6581.                                   and the copyright symbol.
  6582. * minus::                       How to insert a minus sign.
  6583. File: texi.info,  Node: Braces Atsigns Periods,  Next: dmn,  Up: Insertions
  6584. Inserting `@', Braces, and Periods
  6585. ==================================
  6586.    `@' and curly braces are special characters in Texinfo.  To insert
  6587. these characters so they appear in text, you must put an `@' in front
  6588. of these characters to prevent Texinfo from misinterpreting them.
  6589.    Periods are also special.  Depending on whether the period is inside
  6590. or at the end of a sentence, less or more space is inserted after a
  6591. period in a typeset manual.  Since it is not always possible for
  6592. Texinfo to determine when a period ends a sentence and when it is used
  6593. in an abbreviation, special commands are needed in some circumstances.
  6594. (Usually, Texinfo can guess how to handle periods, so you do not need
  6595. to use the special commands; you just enter a period as you would if
  6596. you were using a typewriter, which means you put two spaces after the
  6597. period, question mark, or exclamation mark that ends a sentence.)
  6598.    Do not put braces after any of these commands; they are not
  6599. necessary.
  6600. * Menu:
  6601. * Inserting An Atsign::
  6602. * Inserting Braces::            How to insert `{' and `}'
  6603. * Controlling Spacing::         How to insert the right amount of space
  6604.                                   after punctuation within a sentence.
  6605. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  6606. file texi.texi.
  6607.    This file documents Texinfo, a documentation system that uses a
  6608. single source file to produce both on-line information and a printed
  6609. manual.
  6610.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  6611.    This is the second edition of the Texinfo documentation,
  6612. and is consistent with version 2 of `texinfo.tex'.
  6613.    Permission is granted to make and distribute verbatim copies of this
  6614. manual provided the copyright notice and this permission notice are
  6615. preserved on all copies.
  6616.    Permission is granted to copy and distribute modified versions of
  6617. this manual under the conditions for verbatim copying, provided that
  6618. the entire resulting derived work is distributed under the terms of a
  6619. permission notice identical to this one.
  6620.    Permission is granted to copy and distribute translations of this
  6621. manual into another language, under the above conditions for modified
  6622. versions, except that this permission notice may be stated in a
  6623. translation approved by the Free Software Foundation.
  6624. File: texi.info,  Node: Inserting An Atsign,  Next: Inserting Braces,  Up: Braces Atsigns Periods
  6625. Inserting `@' with @@
  6626. ---------------------
  6627.    `@@' stands for a single `@' in either printed or Info output.
  6628.    Do not put braces after an `@@' command.
  6629. File: texi.info,  Node: Inserting Braces,  Next: Controlling Spacing,  Prev: Inserting An Atsign,  Up: Braces Atsigns Periods
  6630. Inserting `{' and `}'with @{ and @}
  6631. -----------------------------------
  6632.    `@{' stands for a single `{' in either printed or Info output.
  6633.    `@}' stands for a single `}' in either printed or Info output.
  6634.    Do not put braces after either an `@{' or an `@}' command.
  6635. File: texi.info,  Node: Controlling Spacing,  Prev: Inserting Braces,  Up: Braces Atsigns Periods
  6636. Spacing After Colons and Periods
  6637. --------------------------------
  6638.    Use the `@:' command after a period, question mark, exclamation
  6639. mark, or colon that should not be followed by extra space.  For
  6640. example, use `@:' after periods that end abbreviations which are not at
  6641. the ends of sentences.  `@:' has no effect on the Info file output.
  6642.    For example,
  6643.      The s.o.p.@: has three parts ...
  6644.      The s.o.p. has three parts ...
  6645. produces
  6646.      The s.o.p. has three parts ...
  6647.      The s.o.p. has three parts ...
  6648. `@:' has no effect on the Info output.  (`s.o.p' is an acronym for
  6649. "Standard Operating Procedure".)
  6650.    Use `@.' instead of a period at the end of a sentence that ends with
  6651. a single capital letter.  Otherwise, TeX will think the letter is an
  6652. abbreviation and will not insert the correct end-of-sentence spacing.
  6653. Here is an example:
  6654.      Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
  6655.      Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
  6656. produces
  6657.      Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
  6658.      Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
  6659.    In the Info file output, `@.' is equivalent to a simple `.'.
  6660.    The meanings of `@:' and `@.' in Texinfo are designed to work well
  6661. with the Emacs sentence motion commands.  This made it necessary for
  6662. them to be incompatible with some other formatting systems that use
  6663. @-commands.
  6664.    Do not put braces after either an `@:' or an `@.' command.
  6665. File: texi.info,  Node: dmn,  Next: Dots Bullets,  Prev: Braces Atsigns Periods,  Up: Insertions
  6666. `@dmn'{DIMENSION}: Format a Dimension
  6667. =====================================
  6668.    At times, you may want to write `12pt' or `8.5in' with little or no
  6669. space between the number and the abbreviation for the dimension.  You
  6670. can use the `@dmn' command to do this.  On seeing the command, TeX
  6671. inserts just enough space for proper typesetting; the Info formatting
  6672. commands insert no space at all, since the Info file does not require
  6673.    To use the `@dmn' command, write the number and then follow it
  6674. immediately, with no intervening space, by `@dmn', and then by the
  6675. dimension within braces.
  6676. For example,
  6677.      A4 paper is 8.27@dmn{in} wide.
  6678. produces
  6679.      A4 paper is 8.27in wide.
  6680.    Not everyone uses this style.  Instead of writing `8.27@dmn{in}' in
  6681. the Texinfo file, you may write `8.27 in.' or `8.27 inches'.  (In these
  6682. cases, the formatters may insert a line break between the number and the
  6683. dimension.  Also, if you write a period after an abbreviation within a
  6684. sentence, you should write `@:' after the period to prevent TeX from
  6685. inserting extra whitespace.  *Note Spacing After Colons and Periods:
  6686. Controlling Spacing.)
  6687. File: texi.info,  Node: Dots Bullets,  Next: TeX and copyright,  Prev: dmn,  Up: Insertions
  6688. Inserting Ellipsis, Dots, and Bullets
  6689. =====================================
  6690.    An "ellipsis" (a line of dots) is not typeset as a string of
  6691. periods, so a special command is used for ellipsis in Texinfo.  The
  6692. `@bullet' command is special, too.  Each of these commands is followed
  6693. by a pair of braces, `{}', without any whitespace between the name of
  6694. the command and the braces.  (You need to use braces with these
  6695. commands because you can use them next to other text; without the
  6696. braces, the formatters would be confused.  *Note @-Command Syntax:
  6697. Command Syntax, for further information.)
  6698. * Menu:
  6699. * dots::                        How to insert dots ...
  6700. * bullet::                      How to insert a bullet.
  6701. File: texi.info,  Node: dots,  Next: bullet,  Up: Dots Bullets
  6702. `@dots'{}
  6703. ---------
  6704.    Use the `@dots{}' command to generate an ellipsis, which is three
  6705. dots in a row, appropriately spaced, like this: `...'.  Do not simply
  6706. write three periods in the input file; that would work for the Info
  6707. file output, but would produce the wrong amount of space between the
  6708. periods in the printed manual.
  6709. File: texi.info,  Node: bullet,  Prev: dots,  Up: Dots Bullets
  6710. `@bullet'{}
  6711. -----------
  6712.    Use the `@bullet{}' command to generate a large round dot, or the
  6713. closest possible thing to one.  In Info, an asterisk is used.
  6714.    Here is a bullet: *
  6715.    When you use `@bullet' in `@itemize', you do not need to type the
  6716. braces, because `@itemize' supplies them.  *Note itemize::.
  6717. File: texi.info,  Node: TeX and copyright,  Next: minus,  Prev: Dots Bullets,  Up: Insertions
  6718. Inserting TeX and the Copyright Symbol
  6719. ======================================
  6720.    The logo `TeX' is typeset in a special fashion and it needs an
  6721. @-command.  The copyright symbol, `(C)', is also special.  Each of
  6722. these commands is followed by a pair of braces, `{}', without any
  6723. whitespace between the name of the command and the braces.
  6724. * Menu:
  6725. * tex::                         How to insert the TeX logo.
  6726. * copyright symbol::            How to use `@copyright'{}.
  6727. File: texi.info,  Node: tex,  Next: copyright symbol,  Up: TeX and copyright
  6728. `@TeX'{}
  6729. --------
  6730.    Use the `@TeX{}' command to generate `TeX'.  In a printed manual,
  6731. this is a special logo that is different from three ordinary letters.
  6732. In Info, it just looks like `TeX'.  The `@TeX{}' command is unique
  6733. among Texinfo commands in that the T and the X are in upper case.
  6734. File: texi.info,  Node: copyright symbol,  Prev: tex,  Up: TeX and copyright
  6735. `@copyright'{}
  6736. --------------
  6737.    Use the `@copyright{}' command to generate `(C)'.  In a printed
  6738. manual, this is a `c' inside a circle, and in Info, this is `(C)'.
  6739. File: texi.info,  Node: minus,  Prev: TeX and copyright,  Up: Insertions
  6740. `@minus'{}: Inserting a Minus Sign
  6741. ==================================
  6742.    Use the `@minus{}' command to generate a minus sign.  In a
  6743. fixed-width font, this is a single hyphen, but in a proportional font,
  6744. the symbol is the customary length for a minus sign--a little longer
  6745. than a hyphen.
  6746.    You can compare the two forms:
  6747.      `-' is a minus sign generated with `@minus{}',
  6748.      
  6749.      `-' is a hyphen generated with the character `-'.
  6750. In the fixed-width font used by Info, `@minus{}' is the same as a
  6751. hyphen.
  6752.    You should not use `@minus{}' inside `@code' or `@example' because
  6753. the width distinction is not made in the fixed-width font they use.
  6754.    When you use `@minus' to specify the mark beginning each entry in an
  6755. itemized list, you do not need to type the braces (*note itemize::.).
  6756. File: texi.info,  Node: Glyphs,  Next: Breaks,  Prev: Insertions,  Up: Top
  6757. Glyphs for Examples
  6758. *******************
  6759.    In Texinfo, code is often illustrated in examples that are delimited
  6760. by `@example' and `@end example', or by `@lisp' and `@end lisp'.  In
  6761. such examples, you can indicate the results of evaluation or an
  6762. expansion using `=>' or `==>'.  Likewise, there are commands to insert
  6763. glyphs to indicate printed output, error messages, equivalence of
  6764. expressions, and the location of point.
  6765.    The glyph-insertion commands do not need to be used within an
  6766. example, but most often they are.  Every  glyph-insertion command is
  6767. followed by a pair of left- and right-hand braces.
  6768. * Menu:
  6769. * Glyphs Summary::
  6770. * result::                      How to show the result of expression.
  6771. * expansion::                   How to indicate an expansion.
  6772. * Print Glyph::                 How to indicate printed output.
  6773. * Error Glyph::                 How to indicate an error message.
  6774. * Equivalence::                 How to indicate equivalence.
  6775. * Point Glyph::                 How to indicate the location of point.
  6776. File: texi.info,  Node: Glyphs Summary,  Next: result,  Up: Glyphs
  6777. Glyphs Summary
  6778. ==============
  6779.    Here are the different glyph commands:
  6780.      `@result{}' points to the result of an expression.
  6781.      `@expansion{}' shows the results of a macro expansion.
  6782.      `@print{}' indicates printed output.
  6783. error-->
  6784.      `@error{}' indicates that the following text is an error message.
  6785.      `@equiv{}' indicates the exact equivalence of two forms.
  6786.      `@point{}' shows the location of point.
  6787. File: texi.info,  Node: result,  Next: expansion,  Prev: Glyphs Summary,  Up: Glyphs
  6788. =>: Indicating Evaluation
  6789. =========================
  6790.    Use the `@result{}' command to indicate the result of evaluating an
  6791. expression.
  6792.    The `@result{}' command is displayed as `=>' in Info and as a double
  6793. stemmed arrow in the printed output.
  6794.    Thus, the following,
  6795.      (cdr '(1 2 3))
  6796.           => (2 3)
  6797. may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
  6798. File: texi.info,  Node: expansion,  Next: Print Glyph,  Prev: result,  Up: Glyphs
  6799. ==>: Indicating an Expansion
  6800. ============================
  6801.    When an expression is a macro call, it expands into a new expression.
  6802. You can indicate the result of the expansion with the `@expansion{}'
  6803. command.
  6804.    The `@expansion{}' command is displayed as `==>' in Info and as a
  6805. long arrow with a flat base in the printed output.
  6806.    For example, the following
  6807.      @lisp
  6808.      (third '(a b c))
  6809.           @expansion{} (car (cdr (cdr '(a b c))))
  6810.           @result{} c
  6811.      @end lisp
  6812. produces
  6813.      (third '(a b c))
  6814.           ==> (car (cdr (cdr '(a b c))))
  6815.           => c
  6816. which may be read as:
  6817.      `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
  6818.      result of evaluating the expression is `c'.
  6819. Often, as in this case, an example looks better if the `@expansion{}'
  6820. and `@result{}' commands are indented five spaces.
  6821. File: texi.info,  Node: Print Glyph,  Next: Error Glyph,  Prev: expansion,  Up: Glyphs
  6822. -|: Indicating Printed Output
  6823. =============================
  6824.    Sometimes an expression will print output during its execution.  You
  6825. can indicate the printed output with the `@print{}' command.
  6826.    The `@print{}' command is displayed as `-|' in Info and similarly,
  6827. as a horizontal dash butting against a vertical bar, in the printed
  6828. output.
  6829.    In the following example, the printed text is indicated with `-|',
  6830. and the value of the expression follows on the last line.
  6831.      (progn (print 'foo) (print 'bar))
  6832.           -| foo
  6833.           -| bar
  6834.           => bar
  6835. In a Texinfo source file, this example is written as follows:
  6836.      @lisp
  6837.      (progn (print 'foo) (print 'bar))
  6838.           @print{} foo
  6839.           @print{} bar
  6840.           @result{} bar
  6841.      @end lisp
  6842. File: texi.info,  Node: Error Glyph,  Next: Equivalence,  Prev: Print Glyph,  Up: Glyphs
  6843. error-->: Indicating an Error Message
  6844. =====================================
  6845.    A piece of code may cause an error when you evaluate it.  You can
  6846. designate the error message with the `@error{}' command.
  6847.    The `@error{}' command is displayed as `error-->' in Info and as the
  6848. word `error' in a box in the printed output.
  6849.    Thus,
  6850.      @lisp
  6851.      (+ 23 'x)
  6852.      @error{} Wrong type argument: integer-or-marker-p, x
  6853.      @end lisp
  6854. produces
  6855.      (+ 23 'x)
  6856.      error--> Wrong type argument: integer-or-marker-p, x
  6857. This indicates that the following error message is printed when you
  6858. evaluate the expression:
  6859.      Wrong type argument: integer-or-marker-p, x
  6860.    Note that `error-->' itself is not part of the error message.
  6861. File: texi.info,  Node: Equivalence,  Next: Point Glyph,  Prev: Error Glyph,  Up: Glyphs
  6862. ==: Indicating Equivalence
  6863. ==========================
  6864.    Sometimes two expressions produce identical results.  You can
  6865. indicate the exact equivalence of two forms with the `@equiv{}' command.
  6866.    The `@equiv{}' command is displayed as `==' in Info and as a three
  6867. parallel horizontal lines in the printed output.
  6868.    Thus,
  6869.      @lisp
  6870.      (make-sparse-keymap) @equiv{} (list 'keymap)
  6871.      @end lisp
  6872. produces
  6873.      (make-sparse-keymap) == (list 'keymap)
  6874. This indicates that evaluating `(make-sparse-keymap)' produces
  6875. identical results to evaluating `(list 'keymap)'.
  6876. File: texi.info,  Node: Point Glyph,  Prev: Equivalence,  Up: Glyphs
  6877. Indicating Point in a Buffer
  6878. ============================
  6879.    Sometimes you need to show an example of text in an Emacs buffer.  In
  6880. such examples, the convention is to include the entire contents of the
  6881. buffer in question between two lines of dashes containing the buffer
  6882. name.
  6883.    You can use the `@point{}' command to show the location of point in
  6884. the text in the buffer.  (The symbol for point, of course, is not part
  6885. of the text in the buffer; it indicates the place *between* two
  6886. characters where point is located.)
  6887.    The `@point{}' command is displayed as `-!-' in Info and as a small
  6888. five pointed star in the printed output.
  6889.    The following example shows the contents of buffer `foo' before and
  6890. after evaluating a Lisp command to insert the word `changed'.
  6891.      ---------- Buffer: foo ----------
  6892.      This is the -!-contents of foo.
  6893.      ---------- Buffer: foo ----------
  6894.      (insert "changed ")
  6895.           => nil
  6896.      ---------- Buffer: foo ----------
  6897.      This is the changed -!-contents of foo.
  6898.      ---------- Buffer: foo ----------
  6899.    In a Texinfo source file, the example is written like this:
  6900.      @example
  6901.      ---------- Buffer: foo ----------
  6902.      This is the @point{}contents of foo.
  6903.      ---------- Buffer: foo ----------
  6904.      
  6905.      (insert "changed ")
  6906.           @result{} nil
  6907.      ---------- Buffer: foo ----------
  6908.      This is the changed @point{}contents of foo.
  6909.      ---------- Buffer: foo ----------
  6910.      @end example
  6911. File: texi.info,  Node: Breaks,  Next: Definition Commands,  Prev: Glyphs,  Up: Top
  6912. Making and Preventing Breaks
  6913. ****************************
  6914.    Usually, a Texinfo file is processed both by TeX and by one of the
  6915. Info formatting commands.  Line, paragraph, or page breaks sometimes
  6916. occur in the `wrong' place in one or other form of output.  You must
  6917. ensure that text looks right both in the printed manual and in the Info
  6918. file.
  6919.    For example, in a printed manual, page breaks may occur awkwardly in
  6920. the middle of an example; to prevent this, you can hold text together
  6921. using a grouping command that keeps the text from being split across
  6922. two pages.  Conversely, you may want to force a page break where none
  6923. would occur normally.  Fortunately, problems like these do not often
  6924. arise.  When they do, use the break, break prevention, or pagination
  6925. commands.
  6926. * Menu:
  6927. * Break Commands::              Cause and prevent splits.
  6928. * Line Breaks::                 How to force a single line to use two lines.
  6929. * w::                           How to prevent unwanted line breaks.
  6930. * sp::                          How to insert blank lines.
  6931. * page::                        How to force the start of a new page.
  6932. * group::                       How to prevent unwanted page breaks.
  6933. * need::                        Another way to prevent unwanted page breaks.
  6934. File: texi.info,  Node: Break Commands,  Next: Line Breaks,  Up: Breaks
  6935. The Break Commands
  6936. ==================
  6937.    The break commands create line and paragraph breaks:
  6938.      Force a line break.
  6939. `@sp N'
  6940.      Skip N blank lines.
  6941.    The line-break-prevention command holds text together all on one
  6942. line:
  6943. `@w{TEXT}'
  6944.      Prevent TEXT from being split and hyphenated across two lines.
  6945.    The pagination commands apply only to printed output, since Info
  6946. files do not have pages.
  6947. `@page'
  6948.      Start a new page in the printed manual.
  6949. `@group'
  6950.      Hold text together that must appear on one printed page.
  6951. `@need MILS'
  6952.      Start a new printed page if not enough space on this one.
  6953. File: texi.info,  Node: Line Breaks,  Next: w,  Prev: Break Commands,  Up: Breaks
  6954. `@*': Generate Line Breaks
  6955. ==========================
  6956.    The `@*' command forces a line break in both the printed manual and
  6957. in Info.
  6958.    For example,
  6959.      This line @* is broken @*in two places.
  6960. produces
  6961.      This line
  6962.       is broken
  6963.      in two places.
  6964. (Note that the space after the first `@*' command is faithfully carried
  6965. down to the next line.)
  6966.    The `@*' command is often used in a file's copyright page:
  6967.      This is edition 2.0 of the Texinfo documentation,@*
  6968.      and is for ...
  6969. In this case, the `@*' command keeps TeX from stretching the line
  6970. across the whole page in an ugly manner.
  6971.      *Please note:* Do not write braces after an `@*' command; they are
  6972.      not needed.
  6973.      Do not write an `@refill' command at the end of a paragraph
  6974.      containing an `@*' command; it will cause the paragraph to be
  6975.      refilled after the line break occurs, negating the effect of the
  6976.      line break.
  6977. File: texi.info,  Node: w,  Next: sp,  Prev: Line Breaks,  Up: Breaks
  6978. `@w'{TEXT}: Prevent Line Breaks
  6979. ===============================
  6980.    `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
  6981.    You can use the `@w' command to prevent TeX from automatically
  6982. hyphenating a long name or phrase that accidentally falls near the end
  6983. of a line.
  6984.      You can copy GNU software from @w{@file{prep.ai.mit.edu}}.
  6985. produces
  6986.      You can copy GNU software from `prep.ai.mit.edu'.
  6987.    In the Texinfo file, you must write the `@w' command and its
  6988. argument (all the affected text) all on one line.
  6989.      *Caution:* Do not write an `@refill' command at the end of a
  6990.      paragraph containing an `@w' command; it will cause the paragraph
  6991.      to be refilled and may thereby negate the effect of the `@w'
  6992.      command.
  6993. File: texi.info,  Node: sp,  Next: page,  Prev: w,  Up: Breaks
  6994. `@sp' N: Insert Blank Lines
  6995. ===========================
  6996.    A line beginning with and containing only `@sp N' generates N blank
  6997. lines of space in both the printed manual and the Info file.  `@sp'
  6998. also forces a paragraph break.  For example,
  6999.      @sp 2
  7000. generates two blank lines.
  7001.    The `@sp' command is most often used in the title page.
  7002. File: texi.info,  Node: page,  Next: group,  Prev: sp,  Up: Breaks
  7003. `@page': Start a New Page
  7004. =========================
  7005.    A line containing only `@page' starts a new page in a printed
  7006. manual.  The command has no effect on Info files since they are not
  7007. paginated.  An `@page' command is often used in the `@titlepage'
  7008. section of a Texinfo file to start the copyright page.
  7009. File: texi.info,  Node: group,  Next: need,  Prev: page,  Up: Breaks
  7010. `@group': Prevent Page Breaks
  7011. =============================
  7012.    The `@group' command (on a line by itself) is used inside an
  7013. `@example' or similar construct to begin an unsplittable vertical
  7014. group, which will appear entirely on one page in the printed output.
  7015. The group is terminated by a line containing only `@end group'.  These
  7016. two lines produce no output of their own, and in the Info file output
  7017. they have no effect at all.
  7018.    Although `@group' would make sense conceptually in a wide variety of
  7019. contexts, its current implementation works reliably only within
  7020. `@example' and variants, and within `@display', `@format', `@flushleft'
  7021. and `@flushright'.  *Note Quotations and Examples::.  (What all these
  7022. commands have in common is that each line of input produces a line of
  7023. output.)  In other contexts, `@group' can cause anomalous vertical
  7024. spacing.
  7025.    This formatting requirement means that you should write:
  7026.      @example
  7027.      @group
  7028.      ...
  7029.      @end group
  7030.      @end example
  7031. with the `@group' and `@end group' commands inside the `@example' and
  7032. `@end example' commands.
  7033.    The `@group' command is most often used to hold an example together
  7034. on one page.  In this Texinfo manual, more than 100 examples contain
  7035. text that is enclosed between `@group' and `@end group'.
  7036.    If you forget to end a group, you may get strange and unfathomable
  7037. error messages when you run TeX.  This is because TeX keeps trying to
  7038. put the rest of the Texinfo file onto the one page and does not start
  7039. to generate error messages until it has processed considerable text.
  7040. It is a good rule of thumb to look for a missing `@end group' if you
  7041. get incomprehensible error messages in TeX.
  7042. File: texi.info,  Node: need,  Prev: group,  Up: Breaks
  7043. `@need MILS': Prevent Page Breaks
  7044. =================================
  7045.    A line containing only `@need N' starts a new page in a printed
  7046. manual if fewer than N mils (thousandths of an inch) remain on the
  7047. current page.  Do not use braces around the argument N.  The `@need'
  7048. command has no effect on Info files since they are not paginated.
  7049.    This paragraph is preceded by an `@need' command that tells TeX to
  7050. start a new page if fewer than 800 mils (eight-tenths inch) remain on
  7051. the page.  It looks like this:
  7052.      @need 800
  7053.      This paragraph is preceded by ...
  7054.    The `@need' command is useful for preventing orphans (single lines
  7055. at the bottoms of printed pages).
  7056. File: texi.info,  Node: Definition Commands,  Next: Footnotes,  Prev: Breaks,  Up: Top
  7057. Definition Commands
  7058. *******************
  7059.    The `@deffn' command and the other "definition commands" enable you
  7060. to describe functions, variables, macros, commands, user options,
  7061. special forms and other such artifacts in a uniform format.
  7062.    In the Info file, a definition causes the entity
  7063. category--`Function', `Variable', or whatever--to appear at the
  7064. beginning of the first line of the definition, followed by the entity's
  7065. name and arguments.  In the printed manual, the command causes TeX to
  7066. print the entity's name and its arguments on the left margin and print
  7067. the category next to the right margin.  In both output formats, the
  7068. body of the definition is indented.  Also, the name of the entity is
  7069. entered into the appropriate index: `@deffn' enters the name into the
  7070. index of functions, `@defvr' enters it into the index of variables, and
  7071. so on.
  7072.    A manual need not and should not contain more than one definition for
  7073. a given name.  An appendix containing a summary should use `@table'
  7074. rather than the definition commands.
  7075. * Menu:
  7076. * Def Cmd Template::            How to structure a description using a
  7077.                                   definition command.
  7078. * Optional Arguments::          How to handle optional and repeated arguments.
  7079. * deffnx::                      How to group two or more `first' lines.
  7080. * Def Cmds in Detail::          All the definition commands.
  7081. * Def Cmd Conventions::         Conventions for writing definitions.
  7082. * Sample Function Definition::
  7083. File: texi.info,  Node: Def Cmd Template,  Next: Optional Arguments,  Up: Definition Commands
  7084. The Template for a Definition
  7085. =============================
  7086.    The `@deffn' command is used for definitions of entities that
  7087. resemble functions.  To write a definition using the `@deffn' command,
  7088. write the `@deffn' command at the beginning of a line and follow it on
  7089. the same line by the category of the entity, the name of the entity
  7090. itself, and its arguments (if any).  Then write the body of the
  7091. definition on succeeding lines.  (You may embed examples in the body.)
  7092. Finally, end the definition with an `@end deffn' command written on a
  7093. line of its own.  (The other definition commands follow the same
  7094. format.)
  7095.    The template for a definition looks like this:
  7096.      @deffn CATEGORY NAME ARGUMENTS...
  7097.      BODY-OF-DEFINITION
  7098.      @end deffn
  7099. For example,
  7100.      @deffn Command forward-word count
  7101.      This command moves point forward @var{count} words
  7102.      (or backward if @var{count} is negative). ...
  7103.      @end deffn
  7104. produces
  7105.       - Command: forward-word COUNT
  7106.           This function moves point forward COUNT words (or backward if
  7107.           COUNT is negative). ...
  7108.    Capitalize the category name like a title.  If the name of the
  7109. category contains spaces, as in the phrase `Interactive Command', write
  7110. braces around it.  For example:
  7111.      @deffn {Interactive Command} isearch-forward
  7112.      ...
  7113.      @end deffn
  7114. Otherwise, the second word will be mistaken for the name of the entity.
  7115.    Some of the definition commands are more general than others.  The
  7116. `@deffn' command, for example, is the general definition command for
  7117. functions and the like--for entities that may take arguments.  When you
  7118. use this command, you specify the category to which the entity belongs.
  7119. The `@deffn' command possesses three predefined, specialized
  7120. variations, `@defun', `@defmac', and `@defspec', that specify the
  7121. category for you: "Function", "Macro", and "Special Form" respectively.
  7122. The `@defvr' command also is accompanied by several predefined,
  7123. specialized variations for describing particular kinds of variables.
  7124.    The template for a specialized definition, such as `@defun', is
  7125. similar to the template for a generalized definition, except that you
  7126. do not need to specify the category:
  7127.      @defun NAME ARGUMENTS...
  7128.      BODY-OF-DEFINITION
  7129.      @end defun
  7130. Thus,
  7131.      @defun buffer-end flag
  7132.      This function returns @code{(point-min)} if @var{flag}
  7133.      is less than 1, @code{(point-max)} otherwise.
  7134.      ...
  7135.      @end defun
  7136. produces
  7137.       - Function: buffer-end FLAG
  7138.           This function returns `(point-min)' if FLAG is less than 1,
  7139.           `(point-max)' otherwise.  ...
  7140. *Note Sample Function Definition: Sample Function Definition, for a
  7141. more detailed example of a function definition, including the use of
  7142. `@example' inside the definition.
  7143.    The other specialized commands work like `@defun'.
  7144. File: texi.info,  Node: Optional Arguments,  Next: deffnx,  Prev: Def Cmd Template,  Up: Definition Commands
  7145. Optional and Repeated Arguments
  7146. ===============================
  7147.    Some entities take optional or repeated arguments, which may be
  7148. specified by a distinctive glyph that uses square brackets and
  7149. ellipses.  For example, a special form often breaks its argument list
  7150. into separate arguments in more complicated ways than a straightforward
  7151. function.
  7152.    An argument enclosed within square brackets is optional.  Thus,
  7153. [OPTIONAL-ARG] means that OPTIONAL-ARG is optional.  An argument
  7154. followed by an ellipsis is optional and may be repeated more than once.
  7155. Thus, REPEATED-ARGS... stands for zero or more arguments.  Parentheses
  7156. are used when several arguments are grouped into additional levels of
  7157. list structure in Lisp.
  7158.    Here is the `@defspec' line of an example of an imaginary special
  7159. form:
  7160.       - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
  7161. In this example, the arguments FROM and TO are optional, but must both
  7162. be present or both absent.  If they are present, INC may optionally be
  7163. specified as well.  These arguments are grouped with the argument VAR
  7164. into a list, to distinguish them from BODY, which includes all
  7165. remaining elements of the form.
  7166.    In a Texinfo source file, this `@defspec' line is written like this
  7167. (except it would not be split over two lines, as it is in this example).
  7168.      @defspec foobar (@var{var} [@var{from} @var{to}
  7169.           [@var{inc}]]) @var{body}@dots{}
  7170. The function is listed in the Command and Variable Index under `foobar'.
  7171. File: texi.info,  Node: deffnx,  Next: Def Cmds in Detail,  Prev: Optional Arguments,  Up: Definition Commands
  7172. Two or More `First' Lines
  7173. =========================
  7174.    To create two or more `first' or header lines for a definition,
  7175. follow the first `@deffn' line by a line beginning with `@deffnx'.  The
  7176. `@deffnx' command works exactly like `@deffn' except that it does not
  7177. generate extra vertical white space between it and the preceding line.
  7178.    For example,
  7179.      @deffn {Interactive Command} isearch-forward
  7180.      @deffnx {Interactive Command} isearch-backward
  7181.      These two search commands are similar except ...
  7182.      @end deffn
  7183. produces
  7184.  - Interactive Command: isearch-forward
  7185.  - Interactive Command: isearch-backward
  7186.      These two search commands are similar except ...
  7187.    Each of the other definition commands has an `x' form: `@defunx',
  7188. `@defvrx', `@deftypefunx', etc.
  7189.    The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
  7190. File: texi.info,  Node: Def Cmds in Detail,  Next: Def Cmd Conventions,  Prev: deffnx,  Up: Definition Commands
  7191. The Definition Commands
  7192. =======================
  7193.    Texinfo provides more than a dozen definition commands, all of which
  7194. are described in this section.
  7195.    The definition commands automatically enter the name of the entity in
  7196. the appropriate index: for example, `@deffn', `@defun', and `@defmac'
  7197. enter function names in the index of functions; `@defvr' and `@defvar'
  7198. enter variable names in the index of variables.
  7199.    Although the examples that follow mostly illustrate Lisp, the
  7200. commands can be used for other programming languages.
  7201. * Menu:
  7202. * Functions Commands::          Commands for functions and similar entities.
  7203. * Variables Commands::          Commands for variables and similar entities.
  7204. * Typed Functions::             Commands for functions in typed languages.
  7205. * Typed Variables::             Commands for variables in typed languages.
  7206. * Abstract Objects::            Commands for object-oriented programming.
  7207. * Data Types::                  The definition command for data types.
  7208. File: texi.info,  Node: Functions Commands,  Next: Variables Commands,  Up: Def Cmds in Detail
  7209. Functions and Similar Entities
  7210. ------------------------------
  7211.    This section describes the commands for describing functions and
  7212. similar entities:
  7213. `@deffn CATEGORY NAME ARGUMENTS...'
  7214.      The `@deffn' command is the general definition command for
  7215.      functions, interactive commands, and similar entities that may take
  7216.      arguments.  You must choose a term to describe the category of
  7217.      entity being defined; for example, "Function" could be used if the
  7218.      entity is a function.  The `@deffn' command is written at the
  7219.      beginning of a line and is followed on the same line by the
  7220.      category of entity being described, the name of this particular
  7221.      entity, and its arguments, if any.  Terminate the definition with
  7222.      `@end deffn' on a line of its own.
  7223.      For example, here is a definition:
  7224.           @deffn Command forward-char nchars
  7225.           Move point forward @var{nchars} characters.
  7226.           @end deffn
  7227.      This shows a rather terse definition for a "command" named
  7228.      `forward-char' with one argument, NCHARS.
  7229.      `@deffn' prints argument names such as NCHARS in italics or upper
  7230.      case, as if `@var' had been used, because we think of these names
  7231.      as metasyntactic variables--they stand for the actual argument
  7232.      values.  Within the text of the description, write an argument name
  7233.      explicitly with `@var' to refer to the value of the argument.  In
  7234.      the example above, we used `@var{nchars}' in this way.
  7235.      The template for `@deffn' is:
  7236.           @deffn CATEGORY NAME ARGUMENTS...
  7237.           BODY-OF-DEFINITION
  7238.           @end deffn
  7239. `@defun NAME ARGUMENTS...'
  7240.      The `@defun' command is the definition command for functions.
  7241.      `@defun' is equivalent to `@deffn Function ...'.
  7242.      For example,
  7243.           @defun set symbol new-value
  7244.           Change the value of the symbol @var{symbol}
  7245.           to @var{new-value}.
  7246.           @end defun
  7247.      shows a rather terse definition for a function `set' whose
  7248.      arguments are SYMBOL and NEW-VALUE.  The argument names on the
  7249.      `@defun' line automatically appear in italics or upper case as if
  7250.      they were enclosed in `@var'.  Terminate the definition with `@end
  7251.      defun' on a line of its own.
  7252.      The template is:
  7253.           @defun FUNCTION-NAME ARGUMENTS...
  7254.           BODY-OF-DEFINITION
  7255.           @end defun
  7256.      `@defun' creates an entry in the index of functions.
  7257. `@defmac NAME ARGUMENTS...'
  7258.      The `@defmac' command is the definition command for macros.
  7259.      `@defmac' is equivalent to `@deffn Macro ...' and works like
  7260.      `@defun'.
  7261. `@defspec NAME ARGUMENTS...'
  7262.      The `@defspec' command is the definition command for special
  7263.      forms.  (In Lisp, a special form is an entity much like a
  7264.      function.) `@defspec' is equivalent to `@deffn {Special Form} ...'
  7265.      and works like `@defun'.
  7266. File: texi.info,  Node: Variables Commands,  Next: Typed Functions,  Prev: Functions Commands,  Up: Def Cmds in Detail
  7267. Variables and Similar Entities
  7268. ------------------------------
  7269.    Here are the commands for defining variables and similar entities:
  7270. `@defvr CATEGORY NAME'
  7271.      The `@defvr' command is a general definition command for something
  7272.      like a variable--an entity that records a value.  You must choose
  7273.      a term to describe the category of entity being defined; for
  7274.      example, "Variable" could be used if the entity is a variable.
  7275.      Write the `@defvr' command at the beginning of a line and followed
  7276.      it on the same line by the category of the entity and the name of
  7277.      the entity.
  7278.      Capitalize the category name like a title.  If the name of the
  7279.      category contains spaces, as in the name `User Option', write
  7280.      braces around it.  Otherwise, the second word will be mistaken for
  7281.      the name of the entity, for example:
  7282.           @defvr {User Option} fill-column
  7283.           This buffer-local variable specifies
  7284.           the maximum width of filled lines.
  7285.           ...
  7286.           @end defvr
  7287.      Terminate the definition with `@end defvr' on a line of its own.
  7288.      The template is:
  7289.           @defvr CATEGORY NAME
  7290.           BODY-OF-DEFINITION
  7291.           @end defvr
  7292.      `@defvr' creates an entry in the index of variables for NAME.
  7293. `@defvar NAME'
  7294.      The `@defvar' command is the definition command for variables.
  7295.      `@defvar' is equivalent to `@defvr Variable ...'.
  7296.      For example:
  7297.           @defvar kill-ring
  7298.           ...
  7299.           @end defvar
  7300.      The template is:
  7301.           @defvar NAME
  7302.           BODY-OF-DEFINITION
  7303.           @end defvar
  7304.      `@defvar' creates an entry in the index of variables for NAME.
  7305. `@defopt NAME'
  7306.      The `@defopt' command is the definition command for user options.
  7307.      `@defopt' is equivalent to `@defvr {User Option} ...' and works
  7308.      like `@defvar'.
  7309. File: texi.info,  Node: Typed Functions,  Next: Typed Variables,  Prev: Variables Commands,  Up: Def Cmds in Detail
  7310. Functions in Typed Languages
  7311. ----------------------------
  7312.    The `@deftypefn' command and its variations are for describing
  7313. functions in C or any other language in which you must declare types of
  7314. variables and functions.
  7315. `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
  7316.      The `@deftypefn' command is the general definition command for
  7317.      functions and similar entities that may take arguments and that are
  7318.      typed.  The `@deftypefn' command is written at the beginning of a
  7319.      line and is followed on the same line by the category of entity
  7320.      being described, the type of the returned value, the name of this
  7321.      particular entity, and its arguments, if any.
  7322.      For example,
  7323.           @deftypefn {Library Function} int foobar
  7324.              (int @var{foo}, float @var{bar})
  7325.           ...
  7326.           @end deftypefn
  7327.      (where the text before the "...", shown above as two lines, would
  7328.      actually be a single line in a real Texinfo file) produces the
  7329.      following in Info:
  7330.           -- Library Function: int foobar (int FOO, float BAR)
  7331.           ...
  7332.      This means that `foobar' is a "library function" that returns an
  7333.      `int', and its arguments are FOO (an `int') and BAR (a `float').
  7334.      The argument names that you write in `@deftypefn' are not subject
  7335.      to an implicit `@var'--since the actual names of the arguments in
  7336.      `@deftypefn' are typically scattered among data type names and
  7337.      keywords, Texinfo cannot find them without help.  Instead, you
  7338.      must write `@var' explicitly around the argument names.  In the
  7339.      example above, the argument names are `foo' and `bar'.
  7340.      The template for `@deftypefn' is:
  7341.           @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
  7342.           BODY-OF-DESCRIPTION
  7343.           @end deftypefn
  7344.      Note that if the CATEGORY or DATA TYPE is more than one word then
  7345.      it must be enclosed in braces to make it a single argument.
  7346.      If you are describing a procedure in a language that has packages,
  7347.      such as Ada, you might consider using `@deftypefn' in a manner
  7348.      somewhat contrary to the convention described in the preceding
  7349.      paragraphs.
  7350.      For example:
  7351.           @deftypefn stacks private push
  7352.                   (@var{s}:in out stack;
  7353.                   @var{n}:in integer)
  7354.           ...
  7355.           @end deftypefn
  7356.      (The `@deftypefn' arguments are shown split into three lines, but
  7357.      would be a single line in a real Texinfo file.)
  7358.      In this instance, the procedure is classified as belonging to the
  7359.      package `stacks' rather than classified as a `procedure' and its
  7360.      data type is described as `private'.  (The name of the procedure
  7361.      is `push', and its arguments are S and N.)
  7362.      `@deftypefn' creates an entry in the index of functions for NAME.
  7363. `@deftypefun DATA-TYPE NAME ARGUMENTS...'
  7364.      The `@deftypefun' command is the specialized definition command
  7365.      for functions in typed languages.  The command is equivalent to
  7366.      `@deftypefn Function ...'.
  7367.      Thus,
  7368.           @deftypefun int foobar (int @var{foo}, float @var{bar})
  7369.           ...
  7370.           @end deftypefun
  7371.      produces the following in Info:
  7372.           -- Function: int foobar (int FOO, float BAR)
  7373.           ...
  7374.      The template is:
  7375.           @deftypefun TYPE NAME ARGUMENTS...
  7376.           BODY-OF-DESCRIPTION
  7377.           @end deftypefun
  7378.      `@deftypefun' creates an entry in the index of functions for NAME.
  7379. File: texi.info,  Node: Typed Variables,  Next: Abstract Objects,  Prev: Typed Functions,  Up: Def Cmds in Detail
  7380. Variables in Typed Languages
  7381. ----------------------------
  7382.    Variables in typed languages are handled in a manner similar to
  7383. functions in typed languages.  *Note Typed Functions::.  The general
  7384. definition command `@deftypevr' corresponds to `@deftypefn' and the
  7385. specialized definition command `@deftypevar' corresponds to
  7386. `@deftypefun'.
  7387. `@deftypevr CATEGORY DATA-TYPE NAME'
  7388.      The `@deftypevr' command is the general definition command for
  7389.      something like a variable in a typed language--an entity that
  7390.      records a value.  You must choose a term to describe the category
  7391.      of the entity being defined; for example, "Variable" could be used
  7392.      if the entity is a variable.
  7393.      The `@deftypevr' command is written at the beginning of a line and
  7394.      is followed on the same line by the category of the entity being
  7395.      described, the data type, and the name of this particular entity.
  7396.      For example:
  7397.           @deftypevr {Global Flag} int enable
  7398.           ...
  7399.           @end deftypevr
  7400.      produces the following in Info:
  7401.           -- Global Flag: int enable
  7402.           ...
  7403.      The template is:
  7404.           @deftypevr CATEGORY DATA-TYPE NAME
  7405.           BODY-OF-DESCRIPTION
  7406.           @end deftypevr
  7407.      `@deftypevr' creates an entry in the index of variables for NAME.
  7408. `@deftypevar DATA-TYPE NAME'
  7409.      The `@deftypevar' command is the specialized definition command
  7410.      for variables in typed languages.  `@deftypevar' is equivalent to
  7411.      `@deftypevr Variable ...'.
  7412.      For example:
  7413.           @deftypevar int fubar
  7414.           ...
  7415.           @end deftypevar
  7416.      produces the following in Info:
  7417.           -- Variable: int fubar
  7418.           ...
  7419.      The template is:
  7420.           @deftypevar DATA-TYPE NAME
  7421.           BODY-OF-DESCRIPTION
  7422.           @end deftypevar
  7423.      `@deftypevar' creates an entry in the index of variables for NAME.
  7424. File: texi.info,  Node: Abstract Objects,  Next: Data Types,  Prev: Typed Variables,  Up: Def Cmds in Detail
  7425. Object-Oriented Programming
  7426. ---------------------------
  7427.    Here are the commands for formatting descriptions about abstract
  7428. objects, such as are used in object-oriented programming.  A class is a
  7429. defined type of abstract object.  An instance of a class is a
  7430. particular object that has the type of the class.  An instance variable
  7431. is a variable that belongs to the class but for which each instance has
  7432. its own value.
  7433.    In a definition, if the name of a class is truly a name defined in
  7434. the programming system for a class, then you should write an `@code'
  7435. around it.  Otherwise, it is printed in the usual text font.
  7436. `@defcv CATEGORY CLASS NAME'
  7437.      The `@defcv' command is the general definition command for
  7438.      variables associated with classes in object-oriented programming.
  7439.      The `@defcv' command is followed by three arguments: the category
  7440.      of thing being defined, the class to which it belongs, and its
  7441.      name.  Thus,
  7442.           @defcv {Class Option} Window border-pattern
  7443.           ...
  7444.           @end defcv
  7445.      illustrates how you would write the first line of a definition of
  7446.      the `border-pattern' class option of the class `Window'.
  7447.      The template is
  7448.           @defcv CATEGORY CLASS NAME
  7449.           ...
  7450.           @end defcv
  7451.      `@defcv' creates an entry in the index of variables.
  7452. `@defivar CLASS NAME'
  7453.      The `@defivar' command is the definition command for instance
  7454.      variables in object-oriented programming.  `@defivar' is
  7455.      equivalent to `@defcv {Instance Variable} ...'
  7456.      The template is:
  7457.           @defivar CLASS INSTANCE-VARIABLE-NAME
  7458.           BODY-OF-DEFINITION
  7459.           @end defivar
  7460.      `@defivar' creates an entry in the index of variables.
  7461. `@defop CATEGORY CLASS NAME ARGUMENTS...'
  7462.      The `@defop' command is the general definition command for
  7463.      entities that may resemble methods in object-oriented programming.
  7464.      These entities take arguments, as functions do, but are associated
  7465.      with particular classes of objects.
  7466.      For example, some systems have constructs called "wrappers" that
  7467.      are associated with classes as methods are, but that act more like
  7468.      macros than like functions.  You could use `@defop Wrapper' to
  7469.      describe one of these.
  7470.      Sometimes it is useful to distinguish methods and "operations".
  7471.      You can think of an operation as the specification for a method.
  7472.      Thus, a window system might specify that all window classes have a
  7473.      method named `expose'; we would say that this window system
  7474.      defines an `expose' operation on windows in general.  Typically,
  7475.      the operation has a name and also specifies the pattern of
  7476.      arguments; all methods that implement the operation must accept
  7477.      the same arguments, since applications that use the operation do
  7478.      so without knowing which method will implement it.
  7479.      Often it makes more sense to document operations than methods.  For
  7480.      example, window application developers need to know about the
  7481.      `expose' operation, but need not be concerned with whether a given
  7482.      class of windows has its own method to implement this operation.
  7483.      To describe this operation, you would write:
  7484.           @defop Operation windows expose
  7485.      The `@defop' command is written at the beginning of a line and is
  7486.      followed on the same line by the overall name of the category of
  7487.      operation, the name of the class of the operation, the name of the
  7488.      operation, and its arguments, if any.
  7489.      The template is:
  7490.           @defop CATEGORY CLASS NAME ARGUMENTS...
  7491.           BODY-OF-DEFINITION
  7492.           @end defop
  7493.      `@defop' creates an entry, such as ``expose' on `windows'', in the
  7494.      index of functions.
  7495. `@defmethod CLASS NAME ARGUMENTS...'
  7496.      The `@defmethod' command is the definition command for methods in
  7497.      object-oriented programming.  A method is a kind of function that
  7498.      implements an operation for a particular class of objects and its
  7499.      subclasses.  In the Lisp Machine, methods actually were functions,
  7500.      but they were usually defined with `defmethod'.
  7501.      `@defmethod' is equivalent to `@defop Method ...'.  The command is
  7502.      written at the beginning of a line and is followed by the name of
  7503.      the class of the method, the name of the method, and its
  7504.      arguments, if any.
  7505.      For example,
  7506.           @defmethod `bar-class' bar-method argument
  7507.           ...
  7508.           @end defmethod
  7509.      illustrates the definition for a method called `bar-method' of the
  7510.      class `bar-class'.  The method takes an argument.
  7511.      The template is:
  7512.           @defmethod CLASS METHOD-NAME ARGUMENTS...
  7513.           BODY-OF-DEFINITION
  7514.           @end defmethod
  7515.      `@defmethod' creates an entry in the index of functions, such as
  7516.      ``bar-method' on `bar-class''.
  7517. File: texi.info,  Node: Data Types,  Prev: Abstract Objects,  Up: Def Cmds in Detail
  7518. Data Types
  7519. ----------
  7520.    Here is the command for data types:
  7521. `@deftp CATEGORY NAME ATTRIBUTES...'
  7522.      The `@deftp' command is the generic definition command for data
  7523.      types.  The command is written at the beginning of a line and is
  7524.      followed on the same line by the category, by the name of the type
  7525.      (which is a word like `int' or `float'), and then by names of
  7526.      attributes of objects of that type.  Thus, you could use this
  7527.      command for describing `int' or `float', in which case you could
  7528.      use `data type' as the category.  (A data type is a category of
  7529.      certain objects for purposes of deciding which operations can be
  7530.      performed on them.)
  7531.      In Lisp, for example,  "pair" names a particular data type, and an
  7532.      object of that type has two slots called the CAR and the CDR.
  7533.      Here is how you would write the first line of a definition of
  7534.      `pair'.
  7535.           @deftp {Data type} pair car cdr
  7536.           ...
  7537.           @end deftp
  7538.      The template is:
  7539.           @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
  7540.           BODY-OF-DEFINITION
  7541.           @end deftp
  7542.      `@deftp' creates an entry in the index of data types.
  7543. File: texi.info,  Node: Def Cmd Conventions,  Next: Sample Function Definition,  Prev: Def Cmds in Detail,  Up: Definition Commands
  7544. Conventions for Writing Definitions
  7545. ===================================
  7546.    When you write a definition using `@deffn', `@defun', or one of the
  7547. other definition commands, please take care to use arguments that
  7548. indicate the meaning, as with the COUNT argument to the `forward-word'
  7549. function.  Also, if the name of an argument contains the name of a
  7550. type, such as INTEGER, take care that the argument actually is of that
  7551. type.
  7552. File: texi.info,  Node: Sample Function Definition,  Prev: Def Cmd Conventions,  Up: Definition Commands
  7553. A Sample Function Definition
  7554. ============================
  7555.    A function definition uses the `@defun' and `@end defun' commands.
  7556. The name of the function follows immediately after the `@defun' command
  7557. and it is followed, on the same line, by the parameter list.
  7558.    Here is a definition from `The GNU Emacs Lisp Reference Manual'.
  7559. (*Note Calling Functions: (elisp)Calling Functions.)
  7560.       - Function: apply FUNCTION &rest ARGUMENTS
  7561.           `apply' calls FUNCTION with ARGUMENTS, just like `funcall'
  7562.           but with one difference: the last of ARGUMENTS is a list of
  7563.           arguments to give to FUNCTION, rather than a single argument.
  7564.           We also say that this list is "appended" to the other
  7565.           arguments.
  7566.           `apply' returns the result of calling FUNCTION.  As with
  7567.           `funcall', FUNCTION must either be a Lisp function or a
  7568.           primitive function; special forms and macros do not make
  7569.           sense in `apply'.
  7570.                (setq f 'list)
  7571.                     => list
  7572.                (apply f 'x 'y 'z)
  7573.                error--> Wrong type argument: listp, z
  7574.                (apply '+ 1 2 '(3 4))
  7575.                     => 10
  7576.                (apply '+ '(1 2 3 4))
  7577.                     => 10
  7578.                
  7579.                (apply 'append '((a b c) nil (x y z) nil))
  7580.                     => (a b c x y z)
  7581.           An interesting example of using `apply' is found in the
  7582.           description of `mapcar'.
  7583.    In the Texinfo source file, this example looks like this:
  7584.      @defun apply function &rest arguments
  7585.      
  7586.      @code{apply} calls @var{function} with
  7587.      @var{arguments}, just like @code{funcall} but with one
  7588.      difference: the last of @var{arguments} is a list of
  7589.      arguments to give to @var{function}, rather than a single
  7590.      argument.  We also say that this list is @dfn{appended}
  7591.      to the other arguments.
  7592.      
  7593.      @code{apply} returns the result of calling
  7594.      @var{function}.  As with @code{funcall},
  7595.      @var{function} must either be a Lisp function or a
  7596.      primitive function; special forms and macros do not make
  7597.      sense in @code{apply}.
  7598.      
  7599.      @example
  7600.      (setq f 'list)
  7601.           @result{} list
  7602.      (apply f 'x 'y 'z)
  7603.      @error{} Wrong type argument: listp, z
  7604.      (apply '+ 1 2 '(3 4))
  7605.           @result{} 10
  7606.      (apply '+ '(1 2 3 4))
  7607.           @result{} 10
  7608.      
  7609.      (apply 'append '((a b c) nil (x y z) nil))
  7610.           @result{} (a b c x y z)
  7611.      @end example
  7612.      
  7613.      An interesting example of using @code{apply} is found
  7614.      in the description of @code{mapcar}.@refill
  7615.      @end defun
  7616. In this manual, this function is listed in the Command and Variable
  7617. Index under `apply'.
  7618.    Ordinary variables and user options are described using a format like
  7619. that for functions except that variables do not take arguments.
  7620. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  7621. file texi.texi.
  7622.    This file documents Texinfo, a documentation system that uses a
  7623. single source file to produce both on-line information and a printed
  7624. manual.
  7625.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  7626.    This is the second edition of the Texinfo documentation,
  7627. and is consistent with version 2 of `texinfo.tex'.
  7628.    Permission is granted to make and distribute verbatim copies of this
  7629. manual provided the copyright notice and this permission notice are
  7630. preserved on all copies.
  7631.    Permission is granted to copy and distribute modified versions of
  7632. this manual under the conditions for verbatim copying, provided that
  7633. the entire resulting derived work is distributed under the terms of a
  7634. permission notice identical to this one.
  7635.    Permission is granted to copy and distribute translations of this
  7636. manual into another language, under the above conditions for modified
  7637. versions, except that this permission notice may be stated in a
  7638. translation approved by the Free Software Foundation.
  7639. File: texi.info,  Node: Footnotes,  Next: Conditionals,  Prev: Definition Commands,  Up: Top
  7640. Footnotes
  7641. *********
  7642.    A "footnote" is for a reference that documents or elucidates the
  7643. primary text.(1)
  7644.    In Texinfo, footnotes are created with the `@footnote' command.
  7645. This command is followed immediately by a left brace, then by the text
  7646. of the footnote, and then by a terminating right brace.  The template
  7647.      @footnote{TEXT}
  7648.    Footnotes may be of any length, but are usually short.
  7649.    For example, this clause is followed by a sample footnote(2); in the
  7650. Texinfo source, it looks like this:
  7651.      ...a sample footnote @footnote{Here is the sample
  7652.      footnote.}; in the Texinfo source...
  7653.    In a printed manual or book, the reference mark for a footnote is a
  7654. small, superscripted number; the text of the footnote is written at the
  7655. bottom of the page, below a horizontal line.
  7656.    In Info, the reference mark for a footnote is a pair of parentheses
  7657. with the footnote number between them, like this: `(1)'.
  7658.    Info has two footnote styles, which determine where the text of the
  7659. footnote is located:
  7660.    * In the `End' node style, all the footnotes for a single node are
  7661.      placed at the end of that node.  The footnotes are separated from
  7662.      the rest of the node by a line of dashes with the word `Footnotes'
  7663.      within it.  Each footnote begins with an `(N)' reference mark.
  7664.      Here is an example of a single footnote in the end of node style:
  7665.            --------- Footnotes ---------
  7666.           
  7667.           (1)  Here is a sample footnote.
  7668.    * In the `Separate' node style, all the footnotes for a single node
  7669.      are placed in an automatically constructed node of their own.  In
  7670.      this style, a "footnote reference" follows each `(N)' reference
  7671.      mark in the body of the node.  The footnote reference is actually
  7672.      a cross reference which you use to reach the footnote node.
  7673.      The name of the node containing the footnotes is constructed by
  7674.      appending `-Footnotes' to the name of the node that contains the
  7675.      footnotes. (Consequently, the footnotes' node for the `Footnotes'
  7676.      node is `Footnotes-Footnotes'!)  The footnotes' node has an `Up'
  7677.      node pointer that leads back to its parent node.
  7678.      Here is how the first footnote in this manual looks after being
  7679.      formatted for Info in the separate node style:
  7680.           File: texinfo.info  Node: Overview-Footnotes, Up: Overview
  7681.           
  7682.           (1) Note that the first syllable of "Texinfo" is
  7683.           pronounced like "speck", not "hex". ...
  7684.    A Texinfo file may be formatted into an Info file with either
  7685. footnote style.
  7686.    Use the `@footnotestyle' command to specify an Info file's footnote
  7687. style.  Write this command at the beginning of a line followed by an
  7688. argument, either `end' for the end node style or `separate' for the
  7689. separate node style.
  7690.    For example,
  7691.      @footnotestyle end
  7692.      @footnotestyle separate
  7693.    Write an `@footnotestyle' command before or shortly after the
  7694. end-of-header line at the beginning of a Texinfo file.  (If you include
  7695. the `@footnotestyle' command between the start-of-header and
  7696. end-of-header lines, the region formatting commands will format
  7697. footnotes as specified.)
  7698.    If you do not specify a footnote style, the formatting commands use
  7699. their default style.  Currently, `makeinfo' uses the `end' style, while
  7700. `texinfo-format-buffer' and `texinfo-format-region' use the `separate'
  7701. style.
  7702.    This chapter contains two footnotes.
  7703.    ---------- Footnotes ----------
  7704.    (1)  A footnote should complement or expand upon the primary text,
  7705. but a reader should not need to read a footnote to understand the
  7706. primary text.  For a thorough discussion of footnotes, see `The Chicago
  7707. Manual of Style', which is published by the University of Chicago Press.
  7708.    (2)  Here is the sample footnote.
  7709. File: texi.info,  Node: Conditionals,  Next: Format/Print Hardcopy,  Prev: Footnotes,  Up: Top
  7710. Conditionally Visible Text
  7711. **************************
  7712.    Sometimes it is good to use different text for a printed manual and
  7713. its corresponding Info file.  In this case, you can use the
  7714. "conditional commands" to specify which text is for the printed manual
  7715. and which is for the Info file.
  7716. * Menu:
  7717. * Conditional Commands::        How to specify text for Info or TeX.
  7718. * Using Ordinary TeX Commands::  You can use any and all TeX commands.
  7719. * set clear value::             How to designate which text to format (for
  7720.                                   both Info and TeX); and how to set a
  7721.                                   flag to a string that you can insert.
  7722. File: texi.info,  Node: Conditional Commands,  Next: Using Ordinary TeX Commands,  Up: Conditionals
  7723. Using `@ifinfo' and `@iftex'
  7724. ============================
  7725.    `@ifinfo' begins segments of text that should be ignored by TeX when
  7726. it typesets the printed manual.  The segment of text appears only in
  7727. the Info file.  The `@ifinfo' command should appear on a line by
  7728. itself;  end the Info-only text with a line containing `@end ifinfo' by
  7729. itself.  At the beginning of a Texinfo file, the Info permissions are
  7730. contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
  7731. Info Summary and Permissions::.)
  7732.    The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
  7733. and `@end ifinfo' commands, except that they specify text that will
  7734. appear in the printed manual but not in the Info file.
  7735.    For example,
  7736.      @iftex
  7737.      This text will appear only in the printed manual.
  7738.      @end iftex
  7739.      
  7740.      @ifinfo
  7741.      However, this text will appear only in Info.
  7742.      @end ifinfo
  7743. The preceding example produces the following line:
  7744.    However, this text will appear only in Info.
  7745. Note how you only see one of the two lines, depending on whether you
  7746. are reading the Info version or the printed version of this manual.
  7747.    The `@titlepage' command is a special variant of `@iftex' that is
  7748. used for making the title and copyright pages of the printed manual.
  7749. (*Note `@titlepage': titlepage.)
  7750. File: texi.info,  Node: Using Ordinary TeX Commands,  Next: set clear value,  Prev: Conditional Commands,  Up: Conditionals
  7751. Using Ordinary TeX Commands
  7752. ===========================
  7753.    Inside a region delineated by `@iftex' and `@end iftex', you can
  7754. embed some PlainTeX commands.  Info will ignore these commands since
  7755. they are only in that part of the file which is seen by TeX.  You can
  7756. write the TeX commands as you would write them in a normal TeX file,
  7757. except that you must replace the `\' used by TeX with an `@'.  For
  7758. example, in the `@titlepage' section of a Texinfo file, you can use the
  7759. TeX command `@vskip' to format the copyright page.  (The `@titlepage'
  7760. command causes Info to ignore the region automatically, as it does with
  7761. the `@iftex' command.)
  7762.    However, many features of PlainTeX will not work, as they are
  7763. overridden by features of Texinfo.
  7764.    You can enter PlainTeX completely, and use `\' in the TeX commands,
  7765. by delineating a region with the `@tex' and `@end tex' commands.  (The
  7766. `@tex' command also causes Info to ignore the region, like the `@iftex'
  7767. command.)
  7768.    For example, here is a mathematical expression written in PlainTeX:
  7769.      @tex
  7770.      $$ \chi^2 = \sum_{i=1}^N
  7771.                \left (y_i - (a + b x_i)
  7772.                \over \sigma_i\right)^2 $$
  7773.      @end tex
  7774. The output of this example will appear only in a printed manual.  If
  7775. you are reading this in Info, you will not see anything after this
  7776. paragraph.
  7777. File: texi.info,  Node: set clear value,  Prev: Using Ordinary TeX Commands,  Up: Conditionals
  7778. `@set', `@clear', and `@value'
  7779. ==============================
  7780.    You can direct the Texinfo formatting commands to format or ignore
  7781. parts of a Texinfo file with the `@set', `@clear', `@ifset', and
  7782. `@ifclear' commands.
  7783.    In addition, you can use the `@set FLAG' command to set the value of
  7784. FLAG to a string of characters; and use `@value{FLAG}' to insert that
  7785. string.  You can use `@set', for example, to set a date and use
  7786. `@value' to insert the date in several places in the Texinfo file.
  7787. * Menu:
  7788. * ifset ifclear::               Format a region if a flag is set.
  7789. * value::                       Replace a flag with a string.
  7790. * value Example::               An easy way to update edition information.
  7791. File: texi.info,  Node: ifset ifclear,  Next: value,  Up: set clear value
  7792. `@ifset' and `@ifclear'
  7793. -----------------------
  7794.    When a FLAG is set, the Texinfo formatting commands format text
  7795. between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
  7796. When the FLAG is cleared, the Texinfo formatting commands do *not*
  7797. format the text.
  7798.    Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
  7799. can be any single word.  The format for the command looks like this:
  7800.      @set FLAG
  7801.    Write the conditionally formatted text between `@ifset FLAG' and
  7802. `@end ifset' commands, like this:
  7803.      @ifset FLAG
  7804.      CONDITIONAL-TEXT
  7805.      @end ifset
  7806.    For example, you can create one document that has two variants, such
  7807. as a manual for a `large' and `small' model:
  7808.      You can use this machine to dig up shrubs
  7809.      without hurting them.
  7810.      
  7811.      @set large
  7812.      
  7813.      @ifset large
  7814.      It can also dig up fully grown trees.
  7815.      @end ifset
  7816.      
  7817.      Remember to replant promptly ...
  7818. In the example, the formatting commands will format the text between
  7819. `@ifset large' and `@end ifset' because the `large' flag is set.
  7820.    Use the `@clear FLAG' command to turn off, or "clear", a flag.
  7821. Clearing a flag is the opposite of setting a flag.  The command looks
  7822. like this:
  7823.      @clear FLAG
  7824. Write the command on a line of its own.
  7825.    When FLAG is cleared, the Texinfo formatting commands do *not*
  7826. format the text between `@ifset FLAG' and `@end ifset'; that text is
  7827. ignored and does not appear in either printed or Info output.
  7828.    For example, if you clear the flag of the preceding example by
  7829. writing an `@clear large' command after the `@set large' command (but
  7830. before the conditional text), then the Texinfo formatting commands
  7831. ignore the text between the `@ifset large' and `@end ifset' commands.
  7832. In the formatted output, that text does not appear; in both printed and
  7833. Info output, you see only the lines that say, "You can use this machine
  7834. to dig up shrubs without hurting them.  Remember to replant promptly
  7835. ...".
  7836.    If a flag is cleared with an `@clear FLAG' command, then the
  7837. formatting commands format text between subsequent pairs of `@ifclear'
  7838. and `@end ifclear' commands.  But if the flag is set with `@set FLAG',
  7839. then the formatting commands do *not* format text between an `@ifclear'
  7840. and an `@end ifclear' command; rather, they ignore that text.  An
  7841. `@ifclear' command looks like this:
  7842.      @ifclear FLAG
  7843.    In brief, the commands are:
  7844. `@set FLAG'
  7845.      Tell the Texinfo formatting commands that FLAG is set.
  7846. `@clear FLAG'
  7847.      Tell the Texinfo formatting commands that FLAG is cleared.
  7848. `@ifset FLAG'
  7849.      If FLAG is set, tell the Texinfo formatting commands to format the
  7850.      text up to the following `@end ifset' command.
  7851.      If FLAG is cleared, tell the Texinfo formatting commands to ignore
  7852.      text up to the following `@end ifset' command.
  7853. `@ifclear FLAG'
  7854.      If FLAG is set, tell the Texinfo formatting commands to ignore the
  7855.      text up to the following `@end ifclear' command.
  7856.      If FLAG is cleared, tell the Texinfo formatting commands to format
  7857.      the text up to the following `@end ifclear' command.
  7858. File: texi.info,  Node: value,  Next: value Example,  Prev: ifset ifclear,  Up: set clear value
  7859. `@value'
  7860. --------
  7861.    You can use the `@set' command to specify a value for a flag, which
  7862. is expanded by the `@value' command.  The value is a string a
  7863. characters.
  7864.    Write the `@set' command like this:
  7865.      @set foo This is a string.
  7866. This sets the value of `foo' to "This is a string."
  7867.    The Texinfo formatters replace an `@value{FLAG}' command with the
  7868. string to which FLAG is set.
  7869.    Thus, when `foo' is set as shown above, the Texinfo formatters
  7870. convert
  7871.      @value{foo}
  7872.      This is a string.
  7873.    You can write an `@value' command within a paragraph; but you must
  7874. write an `@set' command on a line of its own.
  7875.    If you write the `@set' command like this:
  7876.      @set foo
  7877. without specifying a string, the value of `foo' is an empty string.
  7878.    If you clear a previously set flag with an `@clear FLAG' command, a
  7879. subsequent `@value{flag}' command is invalid and the string is replaced
  7880. with an error message that says `{No value for "FLAG"}'.
  7881.    For example, if you set `foo' as follows:
  7882.      @set how-much very, very, very
  7883. then the formatters transform
  7884.      It is a @value{how-much} wet day.
  7885.      It is a very, very, very wet day.
  7886.    If you write
  7887.      @clear how-much
  7888. then the formatters transform
  7889.      It is a @value{how-much} wet day.
  7890.      It is a {No value for "how-much"} wet day.
  7891. File: texi.info,  Node: value Example,  Prev: value,  Up: set clear value
  7892. `@value' Example
  7893. ----------------
  7894.    You can use the `@value' command to limit the number of places you
  7895. need to change when you record an update to a manual.  Here is how it
  7896. is done in `The GNU Make Manual':
  7897. Set the flags:
  7898.      @set EDITION 0.35 Beta
  7899.      @set VERSION 3.63 Beta
  7900.      @set UPDATED 14 August 1992
  7901.      @set UPDATE-MONTH August 1992
  7902. Write text for the first `@ifinfo' section, for people reading the
  7903. Texinfo file:
  7904.      This is Edition @value{EDITION},
  7905.      last updated @value{UPDATED},
  7906.      of @cite{The GNU Make Manual},
  7907.      for @code{make}, Version @value{VERSION}.
  7908. Write text for the title page, for people reading the printed manual:
  7909.      @title GNU Make
  7910.      @subtitle A Program for Directing Recompilation
  7911.      @subtitle Edition @value{EDITION}, ...
  7912.      @subtitle @value{UPDATE-MONTH}
  7913. (On a printed cover, a date listing the month and the year looks less
  7914. fussy than a date listing the day as well as the month and year.)
  7915. Write text for the Top node, for people reading the Info file:
  7916.      This is Edition @value{EDITION}
  7917.      of the @cite{GNU Make Manual},
  7918.      last updated @value{UPDATED}
  7919.      for @code{make} Version @value{VERSION}.
  7920.    After you format the manual, the text in the first `@ifinfo' section
  7921. looks like this:
  7922.      This is Edition 0.35 Beta, last updated 14 August 1992,
  7923.      of `The GNU Make Manual', for `make', Version 3.63 Beta.
  7924.    When you update the manual, change only the values of the flags; you
  7925. do not need to rewrite the three sections.
  7926. File: texi.info,  Node: Format/Print Hardcopy,  Next: Create an Info File,  Prev: Conditionals,  Up: Top
  7927. Format and Print Hardcopy
  7928. *************************
  7929.    There are three major shell commands for making a printed manual
  7930. from a Texinfo file: one for converting the Texinfo file into a file
  7931. that will be printed, a second for sorting indices, and a third for
  7932. printing the formatted document.  When you use the shell commands, you
  7933. can either work directly in the operating system shell or work within a
  7934. shell inside GNU Emacs.
  7935.    If you are using GNU Emacs, you can use commands provided by Texinfo
  7936. mode instead of shell commands.  In addition to the three commands to
  7937. format a file, sort the indices, and print the result, Texinfo mode
  7938. offers key bindings for commands to recenter the output buffer, show the
  7939. print queue, and delete a job from the print queue.
  7940. * Menu:
  7941. * Use TeX::                     Use TeX to format for hardcopy.
  7942. * Shell Format & Print::        How to format and print a hardcopy manual
  7943.                                  with shell commands.
  7944. * Within Emacs::                How to format and print from an Emacs shell.
  7945. * Texinfo Mode Printing::       How to format and print in Texinfo mode.
  7946. * Compile-Command::             How to print using Emacs's compile command.
  7947. * Requirements Summary::        TeX formatting requirements summary.
  7948. * Preparing for TeX::           What you need to do to use TeX.
  7949. * Overfull hboxes::             What are and what to do with overfull hboxes.
  7950. * smallbook::                   How to print small format books and manuals.
  7951. * A4 Paper::                    How to print on European A4 paper.
  7952. * Cropmarks and Magnification::  How to print marks to indicate the size
  7953.                                 of pages and how to print scaled up output.
  7954. File: texi.info,  Node: Use TeX,  Next: Shell Format & Print,  Up: Format/Print Hardcopy
  7955. Use TeX
  7956. =======
  7957.    The typesetting program called TeX is used for formatting a Texinfo
  7958. file.  TeX is a very powerful typesetting program and, if used right,
  7959. does an exceptionally good job.  *Note How to Obtain TeX: Obtaining
  7960. TeX, for information on how to obtain TeX.
  7961.    The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
  7962. commands read the very same @-commands in the Texinfo file as does TeX,
  7963. but process them differently to make an Info file; see *Note Create an
  7964. Info File::.
  7965. File: texi.info,  Node: Shell Format & Print,  Next: Within Emacs,  Prev: Use TeX,  Up: Format/Print Hardcopy
  7966. Format and Print Using Shell Commands
  7967. =====================================
  7968.    Format the Texinfo file with the shell command `tex' followed by the
  7969. name of the Texinfo file.  This produces a formatted DVI file as well
  7970. as several auxiliary files containing indices, cross references, etc.
  7971. The DVI file (for "DeVice Independent" file) can be printed on a wide
  7972. variety of printers.
  7973.    The `tex' formatting command itself does not sort the indices; it
  7974. writes an output file of unsorted index data.  This is a misfeature of
  7975. TeX.  Hence, to generate a printed index, you first need a sorted index
  7976. to work from.  The `texindex' command sorts indices.  (The source file
  7977. `texindex.c' comes as part of the standard GNU distribution and is
  7978. usually installed when Emacs is installed.)
  7979.    The `tex' formatting command outputs unsorted index files under
  7980. names that obey a standard convention.  These names are the name of
  7981. your main input file to the `tex' formatting command, with everything
  7982. after the first period thrown away, and the two letter names of indices
  7983. added at the end.  For example, the raw index output files for the
  7984. input file `foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn',
  7985. `foo.tp', `foo.pg' and `foo.ky'.  Those are exactly the arguments to
  7986. give to `texindex'.
  7987.    Or else, you can use `??' as "wild-cards" and give the command in
  7988. this form:
  7989.      texindex foo.??
  7990. This command will run `texindex' on all the unsorted index files,
  7991. including any that you have defined yourself using `@defindex' or
  7992. `@defcodeindex'.  (You may execute `texindex foo.??' even if there are
  7993. similarly named files with two letter extensions that are not index
  7994. files, such as `foo.el'.  The `texindex' command reports but otherwise
  7995. ignores such files.)
  7996.    For each file specified, `texindex' generates a sorted index file
  7997. whose name is made by appending `s' to the input file name.  The
  7998. `@printindex' command knows to look for a file of that name.
  7999. `texindex' does not alter the raw index output file.
  8000.    After you have sorted the indices, you need to rerun the `tex'
  8001. formatting command on the Texinfo file.  This regenerates a formatted
  8002. DVI file with up-to-date index entries.(1)
  8003.    To summarize, this is a three step process:
  8004.   1. Run the `tex' formatting command on the Texinfo file.  This
  8005.      generates the formatted DVI file as well as the raw index files
  8006.      with two letter extensions.
  8007.   2. Run the shell command `texindex' on the raw index files to sort
  8008.      them.  This creates the corresponding sorted index files.
  8009.   3. Rerun the `tex' formatting command on the Texinfo file.  This
  8010.      regenerates a formatted DVI file with the index entries in the
  8011.      correct order.  This second run also corrects the page numbers for
  8012.      the cross references.  (The tables of contents are always correct.)
  8013.    You need not run `texindex' each time after you run the `tex'
  8014. formatting.  If you do not, on the next run, the `tex' formatting
  8015. command will use whatever sorted index files happen to exist from the
  8016. previous use of `texindex'.  This is usually OK while you are debugging.
  8017.    Rather than type the `tex' and `texindex' commands yourself, you can
  8018. use `texi2dvi'.  This shell script is designed to simplify the
  8019. `tex'--`texindex'--`tex' sequence by figuring out whether index files
  8020. and DVI files are up-to-date.  It runs `texindex' and `tex' only when
  8021. necessary.
  8022.    The syntax for `texi2dvi' is like this (where `%' is the shell
  8023. prompt):
  8024.      % texi2dvi FILENAME...
  8025.    Finally, you can print the DVI file with the DVI print command.  The
  8026. precise command to use depends on the system; `lpr -d' is common.  The
  8027. DVI print command may require a file name without any extension or with
  8028. a `.dvi' extension.
  8029.    The following commands, for example, sort the indices, format, and
  8030. print the `Bison Manual' (where `%' is the shell prompt):
  8031.      % tex bison.texinfo
  8032.      % texindex bison.??
  8033.      % tex bison.texinfo
  8034.      % lpr -d bison.dvi
  8035. (Remember that the shell commands may be different at your site; but
  8036. these are commonly used versions.)
  8037.    ---------- Footnotes ----------
  8038.    (1)  If you use more than one index and have cross references to an
  8039. index other than the first, you must run `tex' *three times* to get
  8040. correct output: once to generate raw index data; again (after
  8041. `texindex') to output the text of the indices and determine their true
  8042. page numbers; and a third time to output correct page numbers in cross
  8043. references to them.  However, cross references to indices are rare.
  8044. File: texi.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Shell Format & Print,  Up: Format/Print Hardcopy
  8045. From an Emacs Shell ...
  8046. =======================
  8047.    You can give formatting and printing commands from a shell within GNU
  8048. Emacs.  To create a shell within Emacs, type `M-x shell'.  In this
  8049. shell, you can format and print the document.  *Note How to Format and
  8050. Print Using Shell Commands: Shell Format & Print, for details.
  8051.    You can switch to and from the shell buffer while `tex' is running
  8052. and do other editing.  If you are formatting a long document on a slow
  8053. machine, this can be very convenient.
  8054.    You can also use `texi2dvi' from an Emacs shell.  For example, here
  8055. is how to use `texi2dvi' to format and print `Using and Porting GNU CC'
  8056. from a shell within Emacs (where `%' is the shell prompt):
  8057.      % texi2dvi gcc.texinfo
  8058.      % lpr -d gcc.dvi
  8059.    *Note Texinfo Mode Printing::, for more information about formatting
  8060. and printing in Texinfo mode.
  8061. File: texi.info,  Node: Texinfo Mode Printing,  Next: Compile-Command,  Prev: Within Emacs,  Up: Format/Print Hardcopy
  8062. Formatting and Printing in Texinfo Mode
  8063. =======================================
  8064.    Texinfo mode provides several predefined key commands for TeX
  8065. formatting and printing.  These include commands for sorting indices,
  8066. looking at the printer queue, killing the formatting job, and
  8067. recentering the display of the buffer in which the operations occur.
  8068. `C-c C-t C-r'
  8069. `M-x texinfo-tex-region'
  8070.      Run TeX on the current region.
  8071. `C-c C-t C-b'
  8072. `M-x texinfo-tex-buffer'
  8073.      Run TeX on the current buffer.
  8074. `C-c C-t C-i'
  8075. `M-x texinfo-texindex'
  8076.      Sort the indices of a Texinfo file that have been formatted with
  8077.      `texinfo-tex-region' or `texinfo-tex-buffer'.
  8078. `C-c C-t C-p'
  8079. `M-x texinfo-tex-print'
  8080.      Print a DVI file that was made with `texinfo-tex-region' or
  8081.      `texinfo-tex-buffer'.
  8082. `C-c C-t C-q'
  8083. `M-x texinfo-show-tex-print-queue'
  8084.      Show the print queue.
  8085. `C-c C-t C-d'
  8086. `M-x texinfo-delete-from-tex-print-queue'
  8087.      Delete a job from the print queue; you will be prompted for the job
  8088.      number shown by a preceding `C-c C-t C-q' command
  8089.      (`texinfo-show-tex-print-queue').
  8090. `C-c C-t C-k'
  8091. `M-x texinfo-kill-tex-job'
  8092.      Kill either the currently running TeX job that has been started by
  8093.      `texinfo-tex-region' or `texinfo-tex-buffer', or any other process
  8094.      running in the Texinfo shell buffer.
  8095. `C-c C-t C-x'
  8096. `M-x texinfo-quit-tex-job'
  8097.      Quit a TeX formatting job that has stopped because of an error by
  8098.      sending an x to it.  When you do this, TeX preserves a record of
  8099.      what it did in a `.log' file.
  8100. `C-c C-t C-l'
  8101. `M-x texinfo-recenter-tex-output-buffer'
  8102.      Redisplay the shell buffer in which the TeX printing and formatting
  8103.      commands are run to show its most recent output.
  8104.    Thus, the usual sequence of commands for formatting a buffer is as
  8105. follows (with comments to the right):
  8106.      C-c C-t C-b             Run TeX on the buffer.
  8107.      C-c C-t C-i             Sort the indices.
  8108.      C-c C-t C-b             Rerun TeX to regenerate indices.
  8109.      C-c C-t C-p             Print the DVI file.
  8110.      C-c C-t C-q             Display the printer queue.
  8111.    The Texinfo mode TeX formatting commands start a subshell in Emacs
  8112. called the `*texinfo-tex-shell*'.  The `texinfo-tex-command',
  8113. `texinfo-texindex-command', and `tex-dvi-print-command' commands are
  8114. all run in this shell.
  8115.    You can watch the commands operate in the `*texinfo-tex-shell*'
  8116. buffer, and you can switch to and from and use the
  8117. `*texinfo-tex-shell*' buffer as you would any other shell buffer.
  8118.    The formatting and print commands depend on the values of several
  8119. variables.  The default values are:
  8120.           Variable                            Default value
  8121.      
  8122.      texinfo-tex-command                       "tex"
  8123.      texinfo-texindex-command                  "texindex"
  8124.      texinfo-tex-shell-cd-command              "cd"
  8125.      texinfo-tex-dvi-print-command             "lpr -d"
  8126.      texinfo-show-tex-queue-command            "lpq"
  8127.      texinfo-delete-from-print-queue-command   "lprm"
  8128.      texinfo-start-of-header                   "%**start"
  8129.      texinfo-end-of-header                     "%**end"
  8130.      texinfo-tex-trailer                       "@bye"
  8131.    The default values of both the `texinfo-tex-command' and the
  8132. `texinfo-texindex-command' variables are set in the `texnfo-tex.el'
  8133. file.
  8134.    You can change the values of these variables with the `M-x
  8135. edit-options' command (*note Editing Variable Values: (emacs)Edit
  8136. Options.), with the `M-x set-variable' command (*note Examining and
  8137. Setting Variables: (emacs)Examining.), or with your `.emacs'
  8138. initialization file (*note Init File: (emacs)Init File.).
  8139. File: texi.info,  Node: Compile-Command,  Next: Requirements Summary,  Prev: Texinfo Mode Printing,  Up: Format/Print Hardcopy
  8140. Using the Local Variables List
  8141. ==============================
  8142.    Yet another way to apply the TeX formatting command to a Texinfo
  8143. file is to put that command in a "local variables list" at the end of
  8144. the Texinfo file.  You can then specify the TeX formatting command as a
  8145. `compile-command' and have Emacs run the TeX formatting command by
  8146. typing `M-x compile'.  This creates a special shell called the
  8147. `*compilation buffer*' in which Emacs runs the compile command.  For
  8148. example, at the end of the `gdb.texinfo' file, after the `@bye', you
  8149. would put the following:
  8150.      @c Local Variables:
  8151.      @c compile-command: "tex gdb.texinfo"
  8152.      @c End:
  8153. This technique is most often used by programmers who also compile
  8154. programs this way; see *Note Compilation: (emacs)Compilation.
  8155. File: texi.info,  Node: Requirements Summary,  Next: Preparing for TeX,  Prev: Compile-Command,  Up: Format/Print Hardcopy
  8156. TeX Formatting Requirements Summary
  8157. ===================================
  8158.    Every Texinfo file that is to be input to TeX must begin with a
  8159. `\input' command and contain an `@settitle' command:
  8160.      \input texinfo
  8161.      @settitle NAME-OF-MANUAL
  8162. The first command instructs TeX to load the macros it needs to process
  8163. a Texinfo file and the second command specifies the title of printed
  8164. manual.
  8165.    Every Texinfo file must end with a line that terminates TeX
  8166. processing and forces out unfinished pages:
  8167.      @bye
  8168.    Strictly speaking, these three lines are all a Texinfo file needs for
  8169. TeX, besides the body.  (The `@setfilename' line is the only line that
  8170. a Texinfo file needs for Info formatting.)
  8171.    Usually, the file's first line contains an `@c -*-texinfo-*-'
  8172. comment that causes Emacs to switch to Texinfo mode when you edit the
  8173. file.  In addition, the beginning usually includes an `@setfilename'
  8174. for Info formatting, an `@setchapternewpage' command, a title page, a
  8175. copyright page, and permissions.  Besides an `@bye', the end of a file
  8176. usually includes indices and a table of contents.
  8177. For more information, see
  8178. *Note `@setchapternewpage': setchapternewpage,
  8179. *Note Page Headings: Headings,
  8180. *Note Titlepage & Copyright Page::,
  8181. *Note Printing Indices & Menus::, and
  8182. *Note Contents::.
  8183. File: texi.info,  Node: Preparing for TeX,  Next: Overfull hboxes,  Prev: Requirements Summary,  Up: Format/Print Hardcopy
  8184. Preparing to Use TeX
  8185. ====================
  8186. TeX needs to know where to find the `texinfo.tex' file that you have
  8187. told it to input with the `\input texinfo' command at the beginning of
  8188. the first line.  The `texinfo.tex' file tells TeX how to handle
  8189. @-commands.  (`texinfo.tex' is included in the standard GNU
  8190. distributions.)
  8191.    Usually, the `texinfo.tex' file is put in the default directory that
  8192. contains TeX macros (the `/usr/lib/tex/macros' directory) when GNU
  8193. Emacs or other GNU software is installed.  In this case, TeX will find
  8194. the file and you do not need to do anything special.  Alternatively,
  8195. you can put `texinfo.tex' in the directory in which the Texinfo source
  8196. file is located, and TeX will find it there.
  8197.    However, you may want to specify the location of the `\input' file
  8198. yourself.  One way to do this is to write the complete path for the file
  8199. after the `\input' command.  Another way is to set the `TEXINPUTS'
  8200. environment variable in your `.cshrc' or `.profile' file.  The
  8201. `TEXINPUTS' environment variable will tell TeX where to find the
  8202. `texinfo.tex' file and any other file that you might want TeX to use.
  8203.    Whether you use a `.cshrc' or `.profile' file depends on whether you
  8204. use `csh', `sh', or `bash' for your shell command interpreter.  When
  8205. you use `csh', it looks to the `.cshrc' file for initialization
  8206. information, and when you use `sh' or `bash', it looks to the
  8207. `.profile' file.
  8208.    In a `.cshrc' file, you could use the following `csh' command
  8209. sequence:
  8210.      setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
  8211.    In a `.profile' file, you could use the following `sh' command
  8212. sequence:
  8213.      TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
  8214.      export TEXINPUTS
  8215. This would cause TeX to look for `\input' file first in the current
  8216. directory, indicated by the `.', then in a hypothetical user's
  8217. `me/mylib' directory, and finally in the system library.
  8218. File: texi.info,  Node: Overfull hboxes,  Next: smallbook,  Prev: Preparing for TeX,  Up: Format/Print Hardcopy
  8219. Overfull "hboxes"
  8220. =================
  8221.    TeX is sometimes unable to typeset a line without extending it into
  8222. the right margin.  This can occur when TeX comes upon what it
  8223. interprets as a long word that it cannot hyphenate, such as an
  8224. electronic mail network address or a very long title.  When this
  8225. happens, TeX prints an error message like this:
  8226.      Overfull \hbox (20.76302pt too wide)
  8227. (In TeX, lines are in "horizontal boxes", hence the term, "hbox".  The
  8228. backslash, `\', is the TeX equivalent of `@'.)
  8229.    TeX also provides the line number in the Texinfo source file and the
  8230. text of the offending line, which is marked at all the places that TeX
  8231. knows how to hyphenate words.  *Note Catching Errors with TeX
  8232. Formatting: Debugging with TeX, for more information about typesetting
  8233. errors.
  8234.    If the Texinfo file has an overfull hbox, you can rewrite the
  8235. sentence so the overfull hbox does not occur, or you can decide to
  8236. leave it.  A small excursion into the right margin often does not
  8237. matter and may not even be noticeable.
  8238.    However, unless told otherwise, TeX will print a large, ugly, black
  8239. rectangle beside the line that contains the overful hbox.  This is so
  8240. you will notice the location of the problem if you are correcting a
  8241. draft.
  8242.    To prevent such a monstrosity from marring your final printout, write
  8243. the following in the beginning of the Texinfo file on a line of its own,
  8244. before the `@titlepage' command:
  8245.      @finalout
  8246. File: texi.info,  Node: smallbook,  Next: A4 Paper,  Prev: Overfull hboxes,  Up: Format/Print Hardcopy
  8247. Printing "Small" Books
  8248. ======================
  8249.    By default, TeX typesets pages for printing in an 8.5 by 11 inch
  8250. format.  However, you can direct TeX to typeset a document in a 7 by
  8251. 9.25 inch format that is suitable for bound books by inserting the
  8252. following command on a line by itself at the beginning of the Texinfo
  8253. file, before the title page:
  8254.      @smallbook
  8255. (Since regular sized books are often about 7 by 9.25 inches, this
  8256. command might better have been called the `@regularbooksize' command,
  8257. but it came to be called the `@smallbook' command by comparison to the
  8258. 8.5 by 11 inch format.)
  8259.    If you write the `@smallbook' command between the start-of-header
  8260. and end-of-header lines, the Texinfo mode TeX region formatting
  8261. command, `texinfo-tex-region', will format the region in "small" book
  8262. size (*note Start of Header::.).
  8263.    The Free Software Foundation distributes printed copies of `The GNU
  8264. Emacs Manual' and other manuals in the "small" book size.  *Note
  8265. `@smallexample' and `@smalllisp': smallexample & smalllisp, for
  8266. information about commands that make it easier to produce examples for
  8267. a smaller manual.
  8268. File: texi.info,  Node: A4 Paper,  Next: Cropmarks and Magnification,  Prev: smallbook,  Up: Format/Print Hardcopy
  8269. Printing on A4 Paper
  8270. ====================
  8271.    You can tell TeX to typeset a document for printing on European size
  8272. A4 paper with the `@afourpaper' command.  Write the command on a line
  8273. by itself between `@iftex' and `@end iftex' lines near the beginning of
  8274. the Texinfo file, before the title page:
  8275.    For example, this is how you would write the header for this manual:
  8276.      \input texinfo    @c -*-texinfo-*-
  8277.      @c %**start of header
  8278.      @setfilename texinfo
  8279.      @settitle Texinfo
  8280.      @syncodeindex vr fn
  8281.      @iftex
  8282.      @afourpaper
  8283.      @end iftex
  8284.      @c %**end of header
  8285. File: texi.info,  Node: Cropmarks and Magnification,  Prev: A4 Paper,  Up: Format/Print Hardcopy
  8286. Cropmarks and Magnification
  8287. ===========================
  8288.    You can attempt to direct TeX to print cropmarks at the corners of
  8289. pages with the `@cropmarks' command.  Write the `@cropmarks' command on
  8290. a line by itself between `@iftex' and `@end iftex' lines near the
  8291. beginning of the Texinfo file, before the title page, like this:
  8292.      @iftex
  8293.      @cropmarks
  8294.      @end iftex
  8295.    This command is mainly for printers that typeset several pages on one
  8296. sheet of film; but you can attempt to use it to mark the corners of a
  8297. book set to 7 by 9.25 inches with the `@smallbook' command.  (Printers
  8298. will not produce cropmarks for regular sized output that is printed on
  8299. regular sized paper.)  Since different printing machines work in
  8300. different ways, you should explore the use of this command with a
  8301. spirit of adventure.  You may have to redefine the command in the
  8302. `texinfo.tex' definitions file.
  8303.    You can attempt to direct TeX to typeset pages larger or smaller than
  8304. usual with the `\mag' TeX command.  Everything that is typeset is
  8305. scaled proportionally larger or smaller.  (`\mag' stands for
  8306. "magnification".)  This is *not* a Texinfo @-command, but is a PlainTeX
  8307. command that is prefixed with a backslash.  You have to write this
  8308. command between `@tex' and `@end tex' (*note Using Ordinary TeX
  8309. Commands: Using Ordinary TeX Commands.).
  8310.    Follow the `\mag' command with an `=' and then a number that is 1000
  8311. times the magnification you desire.  For example, to print pages at 1.2
  8312. normal size, write the following near the beginning of the Texinfo
  8313. file, before the title page:
  8314.      @tex
  8315.      \mag=1200
  8316.      @end tex
  8317.    With some printing technologies, you can print normal-sized copies
  8318. that look better than usual by using a larger-than-normal master.
  8319.    Depending on your system, `\mag' may not work or may work only at
  8320. certain magnifications.  Be prepared to experiment.
  8321. File: texi.info,  Node: Create an Info File,  Next: Install an Info File,  Prev: Format/Print Hardcopy,  Up: Top
  8322. Creating an Info File
  8323. *********************
  8324.    `makeinfo' is a utility that converts a Texinfo file into an Info
  8325. file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
  8326. functions that do the same.
  8327.    A Texinfo file must possess an `@setfilename' line near its
  8328. beginning, otherwise the Info formatting commands will fail.
  8329.    For information on installing the Info file in the Info system, see
  8330. *Note Install an Info File::.
  8331. * Menu:
  8332. * makeinfo advantages::         `makeinfo' provides better error checking.
  8333. * Invoking makeinfo::            How to run `makeinfo' from a shell.
  8334. * makeinfo options::            Specify fill-column and other options.
  8335. * Pointer Validation::          How to check that pointers point somewhere.
  8336. * makeinfo in Emacs::           How to run `makeinfo' from Emacs.
  8337. * texinfo-format commands::     Two Info formatting commands written
  8338.                                   in Emacs Lisp are an alternative
  8339.                                   to `makeinfo'.
  8340. * Batch Formatting::            How to format for Info in Emacs Batch mode.
  8341. * Tag and Split Files::         How tagged and split files help Info
  8342.                                   to run better.
  8343. File: texi.info,  Node: makeinfo advantages,  Next: Invoking makeinfo,  Up: Create an Info File
  8344. `makeinfo' Preferred
  8345. ====================
  8346.    The `makeinfo' utility creates an Info file from a Texinfo source
  8347. file more quickly than either of the Emacs formatting commands and
  8348. provides better error messages.  We recommend it.  `makeinfo' is a C
  8349. program that is independent of Emacs.  You do not need to run Emacs to
  8350. use `makeinfo', which means you can use `makeinfo' on machines that are
  8351. too small to run Emacs. You can run `makeinfo' in any one of three
  8352. ways: from an operating system shell, from a shell inside Emacs, or by
  8353. typing a key command in Texinfo mode in Emacs.
  8354.    The `texinfo-format-region' and the `texinfo-format-buffer' commands
  8355. are useful if you cannot run `makeinfo'.  Also, in some circumstances,
  8356. they format short regions or buffers more quickly than `makeinfo'.
  8357. File: texi.info,  Node: Invoking makeinfo,  Next: makeinfo options,  Prev: makeinfo advantages,  Up: Create an Info File
  8358. Invoking `makeinfo' from a Shell
  8359. ================================
  8360.    To create an Info file from a Texinfo file, type `makeinfo' followed
  8361. by the name of the Texinfo file.  Thus, to create the Info file for
  8362. Bison, type the following at the shell prompt (where `%' is the prompt):
  8363.      % makeinfo bison.texinfo
  8364.    (You can run a shell inside Emacs by typing `M-x shell'.)
  8365.    Sometimes you will want to specify options.  For example, if you wish
  8366. to discover which version of `makeinfo' you are using, type:
  8367.      % makeinfo --version
  8368.    *Note makeinfo options::, for more information.
  8369. File: texi.info,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Create an Info File
  8370. Options for `makeinfo'
  8371. ======================
  8372.    The `makeinfo' command takes a number of options.  Most often,
  8373. options are used to set the value of the fill column and specify the
  8374. footnote style.  Each command line option is a word preceded by `--'(1)
  8375. or a letter preceded by `-'.  You can use abbreviations for the option
  8376. names as long as they are unique.
  8377.    For example, you could use the following command to create an Info
  8378. file for `bison.texinfo' in which each line is filled to only 68
  8379. columns (where `%' is the prompt):
  8380.      % makeinfo --fill-column=68 bison.texinfo
  8381.    You can write two or more options in sequence, like this:
  8382.      % makeinfo --no-split --fill-column=70 ...
  8383. This would keep the Info file together as one possibly very long file
  8384. and would also set the fill column to 70.
  8385.    The options are:
  8386. `-D VAR'
  8387.      Cause VAR to be defined.  This is equivalent to `@set VAR' in the
  8388.      Texinfo file.
  8389. `--error-limit LIMIT'
  8390.      Set the maximum number of errors that `makeinfo' will report
  8391.      before exiting (on the assumption that continuing would be
  8392.      useless).  The default number of errors that can be reported before
  8393.      `makeinfo' gives up is 100.
  8394. `--fill-column WIDTH'
  8395.      Specify the maximum number of columns in a line; this is the
  8396.      right-hand edge of a line.  Paragraphs that are filled will be
  8397.      filled to this width.  (Filling is the process of breaking up and
  8398.      connecting lines so that lines are the same length as or shorter
  8399.      than the number specified as the fill column.  Lines are broken
  8400.      between words.) The default value for `fill-column' is 72.
  8401. `--footnote-style STYLE'
  8402.      Set the footnote style to STYLE, either `end' for the end node
  8403.      style or `separate' for the separate node style.  The value set by
  8404.      this option overrides the value set in a Texinfo file by an
  8405.      `@footnotestyle' command.  When the footnote style is `separate',
  8406.      `makeinfo' makes a new node containing the footnotes found in the
  8407.      current node.  When the footnote style is `end', `makeinfo' places
  8408.      the footnote references at the end of the current node.
  8409. `-I DIR'
  8410.      Add `dir' to the directory search list for finding files that are
  8411.      included using the `@include' command.  By default, `makeinfo'
  8412.      searches only the current directory.
  8413. `--no-headers'
  8414.      Do not include menus or node lines in the output.  This results in
  8415.      an ASCII file that you cannot read in Info since it does not
  8416.      contain the requisite nodes or menus; but you can print such a
  8417.      file in a single, typewriter-like font and produce acceptable
  8418.      output.
  8419. `--no-split'
  8420.      Suppress the splitting stage of `makeinfo'.  Normally, large
  8421.      output files (where the size is greater than 70k bytes) are split
  8422.      into smaller subfiles, each one approximately 50k bytes.  If you
  8423.      specify `--no-split', `makeinfo' will not split up the output file.
  8424. `--no-pointer-validate'
  8425. `--no-validate'
  8426.      Suppress the pointer-validation phase of `makeinfo'.  Normally,
  8427.      after a Texinfo file is processed, some consistency checks are
  8428.      made to ensure that cross references can be resolved, etc.  *Note
  8429.      Pointer Validation::.
  8430. `--no-warn'
  8431.      Suppress the output of warning messages.  This does *not* suppress
  8432.      the output of error messages, only warnings.  You might want this
  8433.      if the file you are creating has examples of Texinfo cross
  8434.      references within it, and the nodes that are referenced do not
  8435.      actually exist.
  8436. `--no-number-footnotes'
  8437.      Supress automatic footnote numbering.  By default, `makeinfo'
  8438.      numbers each footnote sequentially in a single node, resetting the
  8439.      current footnote number to 1 at the start of each node.
  8440. `--output FILE'
  8441. `-o FILE'
  8442.      Specify that the output should be directed to FILE and not to the
  8443.      file name specified in the `@setfilename' command found in the
  8444.      Texinfo source.  FILE can be the special token `-', which specifies
  8445.      standard output.
  8446. `--paragraph-indent INDENT'
  8447.      Set the paragraph indentation style to INDENT.  The value set by
  8448.      this option overrides the value set in a Texinfo file by an
  8449.      `@paragraphindent' command.  The value of INDENT is interpreted as
  8450.      follows:
  8451.         * If the value of INDENT is `asis', do not change the existing
  8452.           indentation at the starts of paragraphs.
  8453.         * If the value of INDENT is zero, delete any existing
  8454.           indentation.
  8455.         * If the value of INDENT is greater than zero, indent each
  8456.           paragraph by that number of spaces.
  8457. `--reference-limit LIMIT'
  8458.      Set the value of the number of references to a node that
  8459.      `makeinfo' will make without reporting a warning.  If a node has
  8460.      more than this number of references in it, `makeinfo' will make the
  8461.      references but also report a warning.
  8462. `-U VAR'
  8463.      Cause VAR to be undefined.  This is equivalent to `@clear VAR' in
  8464.      the Texinfo file.
  8465. `--verbose'
  8466.      Cause `makeinfo' to display messages saying what it is doing.
  8467.      Normally, `makeinfo' only outputs messages if there are errors or
  8468.      warnings.
  8469. `--version'
  8470.      Report the version number of this copy of `makeinfo'.
  8471.    ---------- Footnotes ----------
  8472.    (1)  `--' has replaced `+', the old introductory character, to
  8473. maintain POSIX.2 compatibility without losing long-named options.
  8474. File: texi.info,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Create an Info File
  8475. Pointer Validation
  8476. ==================
  8477.    `makeinfo' will check the validity of the final Info file unless you
  8478. suppress pointer-validation by using the `--no-pointer-validation'
  8479. option.  Mostly, this means ensuring that nodes you have referenced
  8480. really exist.  Here is a complete list of what is checked:
  8481.   1. If a `Next', `Previous', or `Up' node reference is a reference to a
  8482.      node in the current file and is not an external reference such as
  8483.      to `(dir)', then the referenced node must exist.
  8484.   2. In every node, if the `Previous' node is different from the `Up'
  8485.      node, then the `Previous' node must also be pointed to by a `Next'
  8486.      node.
  8487.   3. Every node except the `Top' node must have an `Up' pointer.
  8488.   4. The node referenced by an `Up' pointer must contain a reference to
  8489.      the current node in some manner other than through a `Next'
  8490.      reference.  This includes menu entries and cross references.
  8491.   5. If the `Next' reference of a node is not the same as the `Next'
  8492.      reference of the `Up' reference, then the node referenced by the
  8493.      `Next' pointer must have a `Previous' pointer that points back to
  8494.      the current node.  This rule allows the last node in a section to
  8495.      point to the first node of the next chapter.
  8496. File: texi.info,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: Pointer Validation,  Up: Create an Info File
  8497. Running `makeinfo' inside Emacs
  8498. ===============================
  8499.    You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
  8500. `makeinfo-region' or the `makeinfo-buffer' commands.  In Texinfo mode,
  8501. the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
  8502. `C-c C-m C-r'
  8503. `M-x makeinfo-region'
  8504.      Format the current region for Info.
  8505. `C-c C-m C-b'
  8506. `M-x makeinfo-buffer'
  8507.      Format the current buffer for Info.
  8508.    When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
  8509. prompts for a file name, offering the name of the visited file as the
  8510. default.  You can edit the default file name in the minibuffer if you
  8511. wish, before typing RET to start the `makeinfo' process.
  8512.    The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
  8513. `makeinfo' program in a temporary shell buffer.  If `makeinfo' finds
  8514. any errors, Emacs displays the error messages in the temporary buffer.
  8515.    You can parse the error messages by typing `C-x `' (`next-error').
  8516. This causes Emacs to go to and position the cursor on the line in the
  8517. Texinfo source that `makeinfo' thinks caused the error.  *Note Running
  8518. `make' or Compilers Generally: (emacs)Compilation, for more information
  8519. about using the `next-error' command.
  8520.    In addition, you can kill the shell in which the `makeinfo' command
  8521. is running or make the shell buffer display its most recent output.
  8522. `C-c C-m C-k'
  8523. `M-x makeinfo-kill-job'
  8524.      Kill the currently running job created by `makeinfo-region' or
  8525.      `makeinfo-buffer'.
  8526. `C-c C-m C-l'
  8527. `M-x makeinfo-recenter-output-buffer'
  8528.      Redisplay the `makeinfo' shell buffer to display its most recent
  8529.      output.
  8530. (Note that the parallel commands for killing and recentering a TeX job
  8531. are `C-c C-t C-k' and `C-c C-t C-l'.  *Note Texinfo Mode Printing::.)
  8532.    You can specify options for `makeinfo' by setting the
  8533. `makeinfo-options' variable with either the `M-x edit-options' or the
  8534. `M-x set-variable' command, or by setting the variable in your `.emacs'
  8535. initialization file.
  8536.    For example, you could write the following in your `.emacs' file:
  8537.      (setq makeinfo-options
  8538.            "--paragraph-indent=0 --no-split
  8539.             --fill-column=70 --verbose")
  8540. For more information, see
  8541. *Note Editing Variable Values: (emacs)Edit Options,
  8542. *Note Examining and Setting Variables: (emacs)Examining,
  8543. *Note Init File: (emacs)Init File, and
  8544. *Note Options for `makeinfo': makeinfo options.
  8545. File: texi.info,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Create an Info File
  8546. The `texinfo-format...' Commands
  8547. ================================
  8548. In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
  8549. file with the `texinfo-format-region' command.  This formats the
  8550. current region and displays the formatted text in a temporary buffer
  8551. called `*Info Region*'.
  8552.    Similarly, you can format a buffer with the `texinfo-format-buffer'
  8553. command.  This command creates a new buffer and generates the Info file
  8554. in it.  Typing `C-x C-s' will save the Info file under the name
  8555. specified by the `@setfilename' line which must be near the beginning
  8556. of the Texinfo file.
  8557. `C-c C-e C-r'
  8558. ``texinfo-format-region''
  8559.      Format the current region for Info.
  8560. `C-c C-e C-b'
  8561. ``texinfo-format-buffer''
  8562.      Format the current buffer for Info.
  8563.    The `texinfo-format-region' and `texinfo-format-buffer' commands
  8564. provide you with some error checking, and other functions can provide
  8565. you with further help in finding formatting errors.  These procedures
  8566. are described in an appendix; see *Note Catching Mistakes::.  However,
  8567. the `makeinfo' program is often faster and provides better error
  8568. checking (*note makeinfo in Emacs::.).
  8569. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  8570. file texi.texi.
  8571.    This file documents Texinfo, a documentation system that uses a
  8572. single source file to produce both on-line information and a printed
  8573. manual.
  8574.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  8575.    This is the second edition of the Texinfo documentation,
  8576. and is consistent with version 2 of `texinfo.tex'.
  8577.    Permission is granted to make and distribute verbatim copies of this
  8578. manual provided the copyright notice and this permission notice are
  8579. preserved on all copies.
  8580.    Permission is granted to copy and distribute modified versions of
  8581. this manual under the conditions for verbatim copying, provided that
  8582. the entire resulting derived work is distributed under the terms of a
  8583. permission notice identical to this one.
  8584.    Permission is granted to copy and distribute translations of this
  8585. manual into another language, under the above conditions for modified
  8586. versions, except that this permission notice may be stated in a
  8587. translation approved by the Free Software Foundation.
  8588. File: texi.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Create an Info File
  8589. Batch Formatting
  8590. ================
  8591.    You can format Texinfo files for Info using `batch-texinfo-format'
  8592. and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
  8593. including a shell inside of Emacs.  (*Note Command Line Switches and
  8594. Arguments: (emacs)Command Switches.)
  8595.    Here is the command to format all the files that end in `.texinfo'
  8596. in the current directory (where `%' is the shell prompt):
  8597.      % emacs -batch -funcall batch-texinfo-format *.texinfo
  8598. Emacs processes all the files listed on the command line, even if an
  8599. error occurs while attempting to format some of them.
  8600.    Run `batch-texinfo-format' only with Emacs in Batch mode as shown;
  8601. it is not interactive.  It kills the Batch mode Emacs on completion.
  8602.    `batch-texinfo-format' is convenient if you lack `makeinfo' and want
  8603. to format several Texinfo files at once.  When you use Batch mode, you
  8604. create a new Emacs process.  This frees your current Emacs, so you can
  8605. continue working in it.  (When you run `texinfo-format-region' or
  8606. `texinfo-format-buffer', you cannot use that Emacs for anything else
  8607. until the command finishes.)
  8608. File: texi.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File
  8609. Tag Files and Split Files
  8610. =========================
  8611.    If a Texinfo file has more than 30,000 bytes,
  8612. `texinfo-format-buffer' automatically creates a tag table for its Info
  8613. file;  `makeinfo' always creates a tag table.  With a "tag table", Info
  8614. can jump to new nodes more quickly than it can otherwise.
  8615.    In addition, if the Texinfo file contains more than about 70,000
  8616. bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
  8617. into shorter "indirect" subfiles of about 50,000 bytes each.  Big files
  8618. are split into smaller files so that Emacs does not need to make a
  8619. large buffer to hold the whole of a large Info file; instead, Emacs
  8620. allocates just enough memory for the small, split off file that is
  8621. needed at the time.  This way, Emacs avoids wasting memory when you run
  8622. Info.  (Before splitting was implemented, Info files were always kept
  8623. short and "include files" were designed as a way to create a single,
  8624. large printed manual out of the smaller Info files.  *Note Include
  8625. Files::, for more information.  Include files are still used for very
  8626. large documents, such as `The Emacs Lisp Reference Manual', in which
  8627. each chapter is a separate file.)
  8628.    When a file is split, Info itself makes use of a shortened version of
  8629. the original file that contains just the tag table and references to
  8630. the files that were split off.  The split off files are called
  8631. "indirect" files.
  8632.    The split off files have names that are created by appending `-1',
  8633. `-2', `-3' and so on to the file name specified by the `@setfilename'
  8634. command.  The shortened version of the original file continues to have
  8635. the name specified by `@setfilename'.
  8636.    At one stage in writing this document, for example, the Info file
  8637. was saved as `test-texinfo' and that file looked like this:
  8638.      Info file: test-texinfo,    -*-Text-*-
  8639.      produced by texinfo-format-buffer
  8640.      from file: new-texinfo-manual.texinfo
  8641.      
  8642.      ^_
  8643.      Indirect:
  8644.      test-texinfo-1: 102
  8645.      test-texinfo-2: 50422
  8646.      test-texinfo-3: 101300
  8647.      ^_^L
  8648.      Tag table:
  8649.      (Indirect)
  8650.      Node: overview^?104
  8651.      Node: info file^?1271
  8652.      Node: printed manual^?4853
  8653.      Node: conventions^?6855
  8654.      ...
  8655. (But `test-texinfo' had far more nodes than are shown here.)  Each of
  8656. the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
  8657. `test-texinfo-3', is listed in this file after the line that says
  8658. `Indirect:'.  The tag table is listed after the line that says `Tag
  8659. table:'.
  8660.    In the list of indirect files, the number following the file name
  8661. records the cumulative number of bytes in the preceding indirect files,
  8662. not counting the file list itself, the tag table, or the permissions
  8663. text in each file.  In the tag table, the number following the node name
  8664. records the location of the beginning of the node, in bytes from the
  8665. beginning.
  8666.    If you are using `texinfo-format-buffer' to create Info files, you
  8667. may want to run the `Info-validate' command.  (The `makeinfo' command
  8668. does such a good job on its own, you do not need `Info-validate'.)
  8669. However, you cannot run the `M-x Info-validate' node-checking command
  8670. on indirect files.  For information on how to prevent files from being
  8671. split and how to validate the structure of the nodes, see *Note Using
  8672. Info-validate::.
  8673. File: texi.info,  Node: Install an Info File,  Next: Command List,  Prev: Create an Info File,  Up: Top
  8674. Installing an Info File
  8675. ***********************
  8676.    Info files are usually kept in the `info' directory.  (You can find
  8677. the location of this directory within Emacs by typing `C-h i' to enter
  8678. Info and then typing `C-x C-f' to see the full pathname to the `info'
  8679. directory.)
  8680. * Menu:
  8681. * Directory file::              The top level menu for all Info files.
  8682. * New Info File::               Listing a new info file.
  8683. * Other Info Directories::      How to specify Info files that are
  8684.                                   located in other directories.
  8685. File: texi.info,  Node: Directory file,  Next: New Info File,  Up: Install an Info File
  8686. The `dir' File
  8687. ==============
  8688.    For Info to work, the `info' directory must contain a file that
  8689. serves as a top level directory for the Info system.  By convention,
  8690. this file is called `dir'.  The `dir' file is itself an Info file.  It
  8691. contains the top level menu for all the Info files in the system.  The
  8692. menu looks like this:
  8693.      * Menu:
  8694.      
  8695.      * Info:    (info).     Documentation browsing system.
  8696.      * Emacs:   (emacs).    The extensible, self-documenting
  8697.                             text editor.
  8698.      * Texinfo: (texinfo).  With one source file, make
  8699.                             either a printed manual using
  8700.                             TeX or an Info file.
  8701.      ...
  8702.    Each of these menu entries points to the `Top' node of the Info file
  8703. that is named in parentheses.  (The menu entry does not need to specify
  8704. the `Top' node, since Info goes to the `Top' node if no node name is
  8705. mentioned.  *Note Nodes in Other Info Files: Other Info Files.)
  8706.    Thus, the `Info' entry points to the `Top' node of the `info' file
  8707. and the `Emacs' entry points to the `Top' node of the `emacs' file.
  8708.    In each of the Info files, the `Up' pointer of the `Top' node refers
  8709. back to the `dir' file.  For example, the line for the `Top' node of
  8710. the Emacs manual looks like this in Info:
  8711.      File: emacs  Node: Top, Up: (DIR), Next: Distrib
  8712. (Note that in this case, the `dir' file name is written in upper case
  8713. letters--it can be written in either upper or lower case.  Info has a
  8714. feature that it will change the case of the file name to lower case if
  8715. it cannot find the name as written.)
  8716. File: texi.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory file,  Up: Install an Info File
  8717. Listing a New Info File
  8718. =======================
  8719.    To add a new Info file to your system, write a menu entry for it in
  8720. the menu in the `dir' file in the `info' directory.  Also, move the new
  8721. Info file itself to the `info' directory.  For example, if you were
  8722. adding documentation for GDB, you would write the following new entry:
  8723.      * GDB: (gdb).           The source-level C debugger.
  8724. The first part of the menu entry is the menu entry name, followed by a
  8725. colon.  The second part is the name of the Info file, in parentheses,
  8726. followed by a period.  The third part is the description.
  8727.    Conventionally, the name of an Info file has a `.info' extension.
  8728. Thus, you might list the name of the file like this:
  8729.      * GDB: (gdb.info).           The source-level C debugger.
  8730. However, Info will look for a file with a `.info' extension if it does
  8731. not find the file under the name given in the menu.  This means that
  8732. you can refer to the file `gdb.info' as `gdb', as shown in the first
  8733. example.  This looks better.
  8734. File: texi.info,  Node: Other Info Directories,  Prev: New Info File,  Up: Install an Info File
  8735. Info Files in Other Directories
  8736. ===============================
  8737.    If an Info file is not in the `info' directory, there are two ways
  8738. to specify its location:
  8739.    * Write the pathname as the menu's second part, or;
  8740.    * Specify the `info' directory name in an environment variable in
  8741.      your `.profile' or `.cshrc' initialization file.  (Only you and
  8742.      others with the same environment variable will be able to find Info
  8743.      files whose location is specified this way.)
  8744.    For example, to reach a test file in the `~bob/manuals' directory,
  8745. you could add an entry like this to the menu in the `dir' file:
  8746.      * Test: (~bob/manuals/info-test).  Bob's own test file.
  8747. In this case, the absolute file name of the `info-test' file is written
  8748. as the second part of the menu entry.
  8749.    Alternatively, you can tell Info where to look by setting the
  8750. `INFOPATH' environment variable in your `.cshrc' or `.profile' file.
  8751.    If you use `sh' or `bash' for your shell command interpreter, you
  8752. must set the `INFOPATH' environment variable in the `.profile'
  8753. initialization file; but if you use `csh', you must set the variable in
  8754. the `.cshrc' initialization file.  The two files require slightly
  8755. different command formats.
  8756.    * In a `.cshrc' file, you could set the `INFOPATH' variable as
  8757.      follows:
  8758.           setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info
  8759.    * In a `.profile' file, you would achieve the same effect by writing:
  8760.           INFOPATH=.:~bob/manuals:/usr/local/emacs/info
  8761.           export INFOPATH
  8762. Either form would cause Info to look first in the current directory,
  8763. indicated by the `.', then in the `~bob/manuals' directory, and finally
  8764. in the `/usr/local/emacs/info' directory (which is a common location
  8765. for the standard Info directory).
  8766. File: texi.info,  Node: Command List,  Next: Tips,  Prev: Install an Info File,  Up: Top
  8767. @-Command List
  8768. **************
  8769.    Here is an alphabetical list of the @-commands in Texinfo.  Square
  8770. brackets, [ ], indicate optional arguments; an ellipsis, `...',
  8771. indicates repeated text.
  8772.      Force a line break. Do not end a paragraph that uses `@*' with an
  8773.      `@refill' command.  *Note Line Breaks::.
  8774.      Stands for a period that really does end a sentence (usually after
  8775.      an end-of-sentence capital letter).  *Note Controlling Spacing::.
  8776.      Indicate to TeX that an immediately preceding period, question
  8777.      mark, exclamation mark, or colon does not end a sentence.  Prevent
  8778.      TeX from inserting extra whitespace as it does at the end of a
  8779.      sentence.  The command has no effect on the Info file output.
  8780.      *Note Controlling Spacing::.
  8781.      Stands for `@'.  *Note Inserting `@': Braces Atsigns Periods.
  8782.      Stands for a left-hand brace, `{'.  *Note Inserting @ braces and
  8783.      periods: Braces Atsigns Periods.
  8784.      Stands for a right-hand brace, `}'.  *Note Inserting @ braces and
  8785.      periods: Braces Atsigns Periods.
  8786. `@appendix TITLE'
  8787.      Begin an appendix.  The title appears in the table of contents of
  8788.      a printed manual.  In Info, the title is underlined with
  8789.      asterisks.  *Note The `@unnumbered' and `@appendix' Commands:
  8790.      unnumbered & appendix.
  8791. `@appendixsec TITLE'
  8792. `@appendixsection TITLE'
  8793.      Begin an appendix section within an appendix.  The section title
  8794.      appears in the table of contents of a printed manual.  In Info,
  8795.      the title is underlined with equal signs.  `@appendixsection' is a
  8796.      longer spelling of the `@appendixsec' command.  *Note Section
  8797.      Commands: unnumberedsec appendixsec heading.
  8798. `@appendixsubsec TITLE'
  8799.      Begin an appendix subsection within an appendix.  The title appears
  8800.      in the table of contents of a printed manual.  In Info, the title
  8801.      is underlined with hyphens.  *Note Subsection Commands:
  8802.      unnumberedsubsec appendixsubsec subheading.
  8803. `@appendixsubsubsec TITLE'
  8804.      Begin an appendix subsubsection within a subappendix.  The title
  8805.      appears in the table of contents of a printed manual.  In Info, the
  8806.      title is underlined with periods.  *Note The `subsub' Commands:
  8807.      subsubsection.
  8808. `@asis'
  8809.      Used following `@table', `@ftable', and `@vtable' to print the
  8810.      table's first column without highlighting ("as is").  *Note Making
  8811.      a Two-column Table: Two-column Tables.
  8812. `@author AUTHOR'
  8813.      Typeset AUTHOR flushleft and underline it.  *Note The `@title' and
  8814.      `@author' Commands: title subtitle author.
  8815. `@b{TEXT}'
  8816.      Print TEXT in bold font.  No effect in Info.  *Note Fonts::.
  8817. `@bullet{}'
  8818.      Generate a large round dot, or the closest possible thing to one.
  8819.      *Note `@bullet': bullet.
  8820. `@bye'
  8821.      Stop formatting a file.  The formatters do not see the contents of
  8822.      a file following an `@bye' command.  *Note Ending a File::.
  8823. `@c COMMENT'
  8824.      Begin a comment in Texinfo.  The rest of the line does not appear
  8825.      in either the Info file or the printed manual.  A synonym for
  8826.      `@comment'.  *Note General Syntactic Conventions: Conventions.
  8827. `@cartouche'
  8828.      Highlight an example or quotation by drawing a box with rounded
  8829.      corners around it.  Pair with `@end cartouche'.  No effect in
  8830.      Info.  *Note Drawing Cartouches Around Examples: cartouche.)
  8831. `@center LINE-OF-TEXT'
  8832.      Center the line of text following the command.  *Note `@center':
  8833.      titlefont center sp.
  8834. `@chapheading TITLE'
  8835.      Print a chapter-like heading in the text, but not in the table of
  8836.      contents of a printed manual.  In Info, the title is underlined
  8837.      with asterisks.  *Note `@majorheading' and `@chapheading':
  8838.      majorheading & chapheading.
  8839. `@chapter TITLE'
  8840.      Begin a chapter.  The chapter title appears in the table of
  8841.      contents of a printed manual.  In Info, the title is underlined
  8842.      with asterisks.  *Note `@chapter': chapter.
  8843. `@cindex ENTRY'
  8844.      Add ENTRY to the index of concepts.  *Note Defining the Entries of
  8845.      an Index: Index Entries.
  8846. `@cite{REFERENCE}'
  8847.      Highlight the name of a book or other reference that lacks a
  8848.      companion Info file.  *Note `@cite': cite.
  8849. `@clear FLAG'
  8850.      Unset FLAG, preventing the Texinfo formatting commands from
  8851.      formatting text between subsequent pairs of `@ifset FLAG' and
  8852.      `@end ifset' commands, and preventing `@value{FLAG}' from
  8853.      expanding to the value to which FLAG is set.  *Note `@set'
  8854.      `@clear' `@value': set clear value.
  8855. `@code{SAMPLE-CODE}'
  8856.      Highlight text that is an expression, a syntactically complete
  8857.      token of a program, or a program name.  *Note `@code': code.
  8858. `@comment COMMENT'
  8859.      Begin a comment in Texinfo.  The rest of the line does not appear
  8860.      in either the Info file or the printed manual.  A synonym for `@c'.
  8861.      *Note General Syntactic Conventions: Conventions.
  8862. `@contents'
  8863.      Print a complete table of contents.  Has no effect in Info, which
  8864.      uses menus instead.  *Note Generating a Table of Contents:
  8865.      Contents.
  8866. `@copyright{}'
  8867.      Generate a copyright symbol.  *Note `@copyright': copyright symbol.
  8868. `@defcodeindex INDEX-NAME'
  8869.      Define a new index and its indexing command.  Print entries in an
  8870.      `@code' font.  *Note Defining New Indices: New Indices.
  8871. `@defcv CATEGORY CLASS NAME'
  8872.      Format a description for a variable associated with a class in
  8873.      object-oriented programming.  Takes three arguments: the category
  8874.      of thing being defined, the class to which it belongs, and its
  8875.      name.  *Note Definition Commands::.
  8876. `@deffn CATEGORY NAME ARGUMENTS...'
  8877.      Format a description for a function, interactive command, or
  8878.      similar entity that may take arguments.  `@deffn' takes as
  8879.      arguments the category of entity being described, the name of this
  8880.      particular entity, and its arguments, if any.  *Note Definition
  8881.      Commands::.
  8882. `@defindex INDEX-NAME'
  8883.      Define a new index and its indexing command.  Print entries in a
  8884.      roman font.  *Note Defining New Indices: New Indices.
  8885. `@defivar CLASS INSTANCE-VARIABLE-NAME'
  8886.      Format a description for an instance variable in object-oriented
  8887.      programming.  The command is equivalent to `@defcv {Instance
  8888.      Variable} ...'.  *Note Definition Commands::.
  8889. `@defmac MACRO-NAME ARGUMENTS...'
  8890.      Format a description for a macro.  The command is equivalent to
  8891.      `@deffn Macro ...'.  *Note Definition Commands::.
  8892. `@defmethod CLASS METHOD-NAME ARGUMENTS...'
  8893.      Format a description for a method in object-oriented programming.
  8894.      The command is equivalent to `@defop Method ...'.  Takes as
  8895.      arguments the name of the class of the method, the name of the
  8896.      method, and its arguments, if any.  *Note Definition Commands::.
  8897. `@defop CATEGORY CLASS NAME ARGUMENTS...'
  8898.      Format a description for an operation in object-oriented
  8899.      programming.  `@defop' takes as arguments the overall name of the
  8900.      category of operation, the name of the class of the operation, the
  8901.      name of the operation, and its arguments, if any.  *Note
  8902.      Definition Commands::.
  8903. `@defopt OPTION-NAME'
  8904.      Format a description for a user option.  The command is equivalent
  8905.      to `@defvr {User Option} ...'.  *Note Definition Commands::.
  8906. `@defspec SPECIAL-FORM-NAME ARGUMENTS...'
  8907.      Format a description for a special form.  The command is
  8908.      equivalent to `@deffn {Special Form} ...'.  *Note Definition
  8909.      Commands::.
  8910. `@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
  8911.      Format a description for a data type.  `@deftp' takes as arguments
  8912.      the category, the name of the type (which is a word like `int' or
  8913.      `float'), and then the names of attributes of objects of that
  8914.      type.  *Note Definition Commands::.
  8915. `@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
  8916.      Format a description for a function or similar entity that may take
  8917.      arguments and that is typed.  `@deftypefn' takes as arguments the
  8918.      classification of entity being described, the type, the name of
  8919.      the entity, and its arguments, if any.  *Note Definition
  8920.      Commands::.
  8921. `@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
  8922.      Format a description for a function in a typed language.  The
  8923.      command is equivalent to `@deftypefn Function ...'.  *Note
  8924.      Definition Commands::.
  8925. `@deftypevr CLASSIFICATION DATA-TYPE NAME'
  8926.      Format a description for something like a variable in a typed
  8927.      language--an entity that records a value.  Takes as arguments the
  8928.      classification of entity being described, the type, and the name of
  8929.      the entity.  *Note Definition Commands::.
  8930. `@deftypevar DATA-TYPE VARIABLE-NAME'
  8931.      Format a description for a variable in a typed language.  The
  8932.      command is equivalent to `@deftypevr Variable ...'.  *Note
  8933.      Definition Commands::.
  8934. `@defun FUNCTION-NAME ARGUMENTS...'
  8935.      Format a description for functions.  The command is equivalent to
  8936.      `@deffn Function ...'.  *Note Definition Commands::.
  8937. `@defvar VARIABLE-NAME'
  8938.      Format a description for variables.  The command is equivalent to
  8939.      `@defvr Variable ...'.  *Note Definition Commands::.
  8940. `@defvr CATEGORY NAME'
  8941.      Format a description for any kind of variable.  `@defvr' takes as
  8942.      arguments the category of the entity and the name of the entity.
  8943.      *Note Definition Commands::.
  8944. `@dfn{TERM}'
  8945.      Highlight the introductory or defining use of a term.  *Note
  8946.      `@dfn': dfn.
  8947. `@display'
  8948.      Begin a kind of example.  Indent text, do not fill, do not select a
  8949.      new font.  Pair with `@end display'.  *Note `@display': display.
  8950. `@dmn{DIMENSION}'
  8951.      Format a dimension.  Cause TeX to insert a narrow space before
  8952.      DIMENSION.  No effect in Info.  Use for writing a number followed
  8953.      by an abbreviation of a dimension name, such as `12pt', written as
  8954.      `12@dmn{pt}', with no space between the number and the `@dmn'
  8955.      command.  *Note `@dmn': dmn.
  8956. `@dots{}'
  8957.      Insert an ellipsis: `...'.  *Note `@dots': dots.
  8958. `@emph{TEXT}'
  8959.      Highlight TEXT; text is displayed in *italics* in printed output,
  8960.      and surrounded by asterisks in Info.  *Note Emphasizing Text:
  8961.      Emphasis.
  8962. `@enumerate [NUMBER-OR-LETTER]'
  8963.      Begin a numbered list, using `@item' for each entry.  Optionally,
  8964.      start list with NUMBER-OR-LETTER.  Pair with `@end enumerate'.
  8965.      *Note `@enumerate': enumerate.
  8966. `@equiv{}'
  8967.      Indicate to the reader the exact equivalence of two forms with a
  8968.      glyph: `=='.  *Note Equivalence::.
  8969. `@error{}'
  8970.      Indicate to the reader with a glyph that the following text is an
  8971.      error message: `error-->'.  *Note Error Glyph::.
  8972. `@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
  8973.      Specify page footings for even-numbered (left-hand) pages.  Not
  8974.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  8975.      Headings.
  8976. `@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
  8977.      Specify page headings for even-numbered (left-hand) pages.  Not
  8978.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  8979.      Headings.
  8980. `@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
  8981.      Specify page footings for every page.  Not relevant to Info.
  8982.      *Note How to Make Your Own Headings: Custom Headings.
  8983. `@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
  8984.      Specify page headings for every page.  Not relevant to Info.
  8985.      *Note How to Make Your Own Headings: Custom Headings.
  8986. `@example'
  8987.      Begin an example.  Indent text, do not fill, and select
  8988.      fixed-width font.  Pair with `@end example'.  *Note `@example':
  8989.      example.
  8990. `@exdent LINE-OF-TEXT'
  8991.      Remove any indentation a line might have.  *Note Undoing the
  8992.      Indentation of a Line: exdent.
  8993. `@expansion{}'
  8994.      Indicate the result of a macro expansion to the reader with a
  8995.      special glyph: `==>'.  *Note ==> Indicating an Expansion:
  8996.      expansion.
  8997. `@file{FILENAME}'
  8998.      Highlight the name of a file, buffer, node, or directory.  *Note
  8999.      `@file': file.
  9000. `@finalout'
  9001.      Prevent TeX from printing large black warning rectangles beside
  9002.      over-wide lines.  *Note Overfull hboxes::.
  9003. `@findex ENTRY'
  9004.      Add ENTRY to the index of functions.  *Note Defining the Entries
  9005.      of an Index: Index Entries.
  9006. `@flushleft'
  9007.      Left justify every line but leave the right end ragged.  Leave
  9008.      font as is.  Pair with `@end flushleft'.  *Note `@flushleft' and
  9009.      `@flushright': flushleft & flushright.
  9010. `@flushright'
  9011.      Right justify every line but leave the left end ragged.  Leave
  9012.      font as is.  Pair with `@end flushright'.  *Note `@flushleft' and
  9013.      `@flushright': flushleft & flushright.
  9014. `@footnote{TEXT-OF-FOOTNOTE}'
  9015.      Enter a footnote.  Footnote text is printed at the bottom of the
  9016.      page by TeX; Info may format in either `End' node or `Separate'
  9017.      node style.  *Note Footnotes::.
  9018. `@footnotestyle STYLE'
  9019.      Specify an Info file's footnote style, either `end' for the end
  9020.      node style or `separate' for the separate node style.  *Note
  9021.      Footnotes::.
  9022. `@format'
  9023.      Begin a kind of example.  Like `@example' or `@display', but do
  9024.      not narrow the margins and do not select the fixed-width font.
  9025.      Pair with `@end format'.  *Note `@example': example.
  9026. `@ftable FORMATTING-COMMAND'
  9027.      Begin a two-column table, using `@item' for each entry.
  9028.      Automatically enter each of the items in the first column into the
  9029.      index of functions.  Pair with `@end ftable'.  The same as
  9030.      `@table', except for indexing.  *Note `@ftable' and `@vtable':
  9031.      ftable vtable.
  9032. `@group'
  9033.      Hold text together that must appear on one printed page.  Pair with
  9034.      `@end group'.  Not relevant to Info.  *Note `@group': group.
  9035. `@heading TITLE'
  9036.      Print an unnumbered section-like heading in the text, but not in
  9037.      the table of contents of a printed manual.  In Info, the title is
  9038.      underlined with equal signs.  *Note Section Commands:
  9039.      unnumberedsec appendixsec heading.
  9040. `@headings ON-OFF-SINGLE-DOUBLE'
  9041.      Turn page headings on or off, or specify single-sided or
  9042.      double-sided page headings for printing.  `@headings on' is
  9043.      synonymous with `@headings double'.  *Note The `@headings'
  9044.      Command: headings on off.
  9045. `@i{TEXT}'
  9046.      Print TEXT in italic font.  No effect in Info.  *Note Fonts::.
  9047. `@ifclear FLAG'
  9048.      If FLAG is cleared, the Texinfo formatting commands format text
  9049.      between `@ifclear FLAG' and the following `@end ifclear' command.
  9050.      *Note `@set' `@clear' `@value': set clear value.
  9051. `@ifinfo'
  9052.      Begin a stretch of text that will be ignored by TeX when it
  9053.      typesets the printed manual.  The text appears only in the Info
  9054.      file.  Pair with `@end ifinfo'.  *Note Conditionally Visible Text:
  9055.      Conditionals.
  9056. `@ifset FLAG'
  9057.      If FLAG is set, the Texinfo formatting commands format text
  9058.      between `@ifset FLAG' and the following `@end ifset' command.
  9059.      *Note `@set' `@clear' `@value': set clear value.
  9060. `@iftex'
  9061.      Begin a stretch of text that will not appear in the Info file, but
  9062.      will be processed only by TeX.  Pair with `@end iftex'.  *Note
  9063.      Conditionally Visible Text: Conditionals.
  9064. `@ignore'
  9065.      Begin a stretch of text that will not appear in either the Info
  9066.      file or the printed output.  Pair with `@end ignore'.  *Note
  9067.      Comments and Ignored Text: Comments.
  9068. `@include FILENAME'
  9069.      Incorporate the contents of the file FILENAME into the Info file
  9070.      or printed document.  *Note Include Files::.
  9071. `@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
  9072.      Make a cross reference to an Info file for which there is no
  9073.      printed manual.  *Note Cross references using `@inforef': inforef.
  9074. `\input MACRO-DEFINITIONS-FILE'
  9075.      Use the specified macro definitions file.  This command is used
  9076.      only in the first line of a Texinfo file to cause TeX to make use
  9077.      of the `texinfo' macro definitions file.  The backslash in `\input'
  9078.      is used instead of an `@' because TeX does not properly recognize
  9079.      `@' until after it has read the definitions file.  *Note The
  9080.      Texinfo File Header: Header.
  9081. `@item'
  9082.      Indicate the beginning of a marked paragraph for `@itemize' and
  9083.      `@enumerate'; indicate the beginning of the text of a first column
  9084.      entry for `@table', `@ftable', and `@vtable'.  *Note Lists and
  9085.      Tables::.
  9086. `@itemize  MARK-GENERATING-CHARACTER-OR-COMMAND'
  9087.      Produce a sequence of indented paragraphs, with a mark inside the
  9088.      left margin at the beginning of each paragraph.  Pair with `@end
  9089.      itemize'.  *Note `@itemize': itemize.
  9090. `@itemx'
  9091.      Like `@item' but do not generate extra vertical space above the
  9092.      item text.  *Note `@itemx': itemx.
  9093. `@kbd{KEYBOARD-CHARACTERS}'
  9094.      Indicate text that consists of characters of input to be typed by
  9095.      users.  *Note `@kbd': kbd.
  9096. `@key{KEY-NAME}'
  9097.      Highlight KEY-NAME, a conventional name for a key on a keyboard.
  9098.      *Note `@key': key.
  9099. `@kindex ENTRY'
  9100.      Add ENTRY to the index of keys.  *Note Defining the Entries of an
  9101.      Index: Index Entries.
  9102. `@lisp'
  9103.      Begin an example of Lisp code.  Indent text, do not fill, and
  9104.      select fixed-width font.  Pair with `@end lisp'.  *Note `@lisp':
  9105.      Lisp Example.
  9106. `@majorheading  TITLE'
  9107.      Print a chapter-like heading in the text, but not in the table of
  9108.      contents of a printed manual.  Generate more vertical whitespace
  9109.      before the heading than the `@chapheading' command.  In Info, the
  9110.      chapter heading line is underlined with asterisks.  *Note
  9111.      `@majorheading' and `@chapheading': majorheading & chapheading.
  9112. `@menu'
  9113.      Mark the beginning of a menu of nodes in Info.  No effect in a
  9114.      printed manual.  Pair with `@end menu'.  *Note Menus::.
  9115. `@minus{}'
  9116.      Generate a minus sign.  *Note `@minus': minus.
  9117. `@need N'
  9118.      Start a new page in a printed manual if fewer than N mils
  9119.      (thousandths of an inch) remain on the current page.  *Note
  9120.      `@need': need.
  9121. `@node NAME, NEXT, PREVIOUS, UP'
  9122.      Define the beginning of a new node in Info, and serve as a locator
  9123.      for references for TeX.  *Note `@node': node.
  9124. `@noindent'
  9125.      Prevent text from being indented as if it were a new paragraph.
  9126.      *Note `@noindent': noindent.
  9127. `@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
  9128.      Specify page footings for odd-numbered (right-hand) pages.  Not
  9129.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  9130.      Headings.
  9131. `@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
  9132.      Specify page headings for odd-numbered (right-hand) pages.  Not
  9133.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  9134.      Headings.
  9135. `@page'
  9136.      Start a new page in a printed manual.  No effect in Info.  *Note
  9137.      `@page': page.
  9138. `@paragraphindent INDENT'
  9139.      Indent paragraphs by INDENT number of spaces; delete indentation
  9140.      if the value of INDENT is 0; and do not change indentation if
  9141.      INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
  9142. `@pindex ENTRY'
  9143.      Add ENTRY to the index of programs.  *Note Defining the Entries of
  9144.      an Index: Index Entries.
  9145. `@point{}'
  9146.      Indicate the position of point in a buffer to the reader with a
  9147.      glyph: `-!-'.  *Note Indicating Point in a Buffer: Point Glyph.
  9148. `@print{}'
  9149.      Indicate printed output to the reader with a glyph: `-|'.  *Note
  9150.      Print Glyph::.
  9151. `@printindex INDEX-NAME'
  9152.      Print an alphabetized two-column index in a printed manual or
  9153.      generate an alphabetized menu of index entries for Info.  *Note
  9154.      Printing Indices & Menus::.
  9155. `@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  9156.      Make a reference that starts with a lower case `see' in a printed
  9157.      manual.  Use within parentheses only.  Do not follow command with a
  9158.      punctuation mark.  The Info formatting commands automatically
  9159.      insert terminating punctuation as needed, which is why you do not
  9160.      need to insert punctuation.  Only the first argument is mandatory.
  9161.      *Note `@pxref': pxref.
  9162. `@quotation'
  9163.      Narrow the margins to indicate text that is quoted from another
  9164.      real or imaginary work.  Write command on a line of its own.  Pair
  9165.      with `@end quotation'.  *Note `@quotation': quotation.
  9166. `@r{TEXT}'
  9167.      Print TEXT in roman font.  No effect in Info.  *Note Fonts::.
  9168. `@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  9169.      Make a reference.  In a printed manual, the reference does not
  9170.      start with a `See'.  Follow command with a punctuation mark.  Only
  9171.      the first argument is mandatory.  *Note `@ref': ref.
  9172. `@refill'
  9173.      In Info, refill and indent the paragraph after all the other
  9174.      processing has been done.  No effect on TeX, which always refills.
  9175.      This command is no longer needed, since all formatters now
  9176.      automatically refill.  *Note Refilling Paragraphs::.
  9177. `@result{}'
  9178.      Indicate the result of an expression to the reader with a special
  9179.      glyph: `=>'.  *Note `@result': result.
  9180. `@samp{TEXT}'
  9181.      Highlight TEXT that is a literal example of a sequence of
  9182.      characters.  Used for single characters, for statements, and often
  9183.      for entire shell commands.  *Note `@samp': samp.
  9184. `@sc{TEXT}'
  9185.      Set TEXT in a printed output in THE SMALL CAPS FONT and set text
  9186.      in the Info file in uppercase letters.  *Note Smallcaps::.
  9187. `@section TITLE'
  9188.      Begin a section within a chapter.  In a printed manual, the section
  9189.      title is numbered and appears in the table of contents.  In Info,
  9190.      the title is underlined with equal signs.  *Note `@section':
  9191.      section.
  9192. `@set FLAG [STRING]'
  9193.      Make FLAG active, causing the Texinfo formatting commands to
  9194.      format text between subsequent pairs of `@ifset FLAG' and `@end
  9195.      ifset' commands.  Optionally, set value of FLAG to STRING.  *Note
  9196.      `@set' `@clear' `@value': set clear value.
  9197. `@setchapternewpage ON-OFF-ODD'
  9198.      Specify whether chapters start on new pages, and if so, whether on
  9199.      odd-numbered (right-hand) new pages.  *Note `@setchapternewpage':
  9200.      setchapternewpage.
  9201. `@setfilename INFO-FILE-NAME'
  9202.      Provide a name for the Info file.  *Note General Syntactic
  9203.      Conventions: Conventions.
  9204. `@settitle TITLE'
  9205.      Provide a title for page headers in a printed manual.  *Note
  9206.      General Syntactic Conventions: Conventions.
  9207. `@shortcontents'
  9208.      Print a short table of contents.  Not relevant to Info, which uses
  9209.      menus rather than tables of contents.  A synonym for
  9210.      `@summarycontents'.  *Note Generating a Table of Contents:
  9211.      Contents.
  9212. `@smallbook'
  9213.      Cause TeX to produce a printed manual in a 7 by 9.25 inch format
  9214.      rather than the regular 8.5 by 11 inch format.  *Note Printing
  9215.      Small Books: smallbook.  Also, see *Note `@smallexample' and
  9216.      `@smalllisp': smallexample & smalllisp.
  9217. `@smallexample'
  9218.      Indent text to indicate an example.  Do not fill, select
  9219.      fixed-width font.  In `@smallbook' format, print text in a smaller
  9220.      font than with `@example'.  Pair with `@end smallexample'.  *Note
  9221.      `@smallexample' and `@smalllisp': smallexample & smalllisp.
  9222. `@smalllisp'
  9223.      Begin an example of Lisp code.  Indent text, do not fill, select
  9224.      fixed-width font.  In `@smallbook' format, print text in a smaller
  9225.      font.  Pair with `@end smalllisp'.  *Note `@smallexample' and
  9226.      `@smalllisp': smallexample & smalllisp.
  9227. `@sp N'
  9228.      Skip N blank lines.  *Note `@sp': sp.
  9229. `@strong TEXT'
  9230.      Emphasize TEXT by typesetting it in a *bold* font for the printed
  9231.      manual and by surrounding it with asterisks for Info.  *Note
  9232.      Emphasizing Text: emph & strong.
  9233. `@subheading TITLE'
  9234.      Print an unnumbered subsection-like heading in the text, but not in
  9235.      the table of contents of a printed manual.  In Info, the title is
  9236.      underlined with hyphens.  *Note `@unnumberedsubsec'
  9237.      `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
  9238.      subheading.
  9239. `@subsection TITLE'
  9240.      Begin a subsection within a section.  In a printed manual, the
  9241.      subsection title is numbered and appears in the table of contents.
  9242.      In Info, the title is underlined with hyphens.  *Note
  9243.      `@subsection': subsection.
  9244. `@subsubheading TITLE'
  9245.      Print an unnumbered subsubsection-like heading in the text, but
  9246.      not in the table of contents of a printed manual.  In Info, the
  9247.      title is underlined with periods.  *Note The `subsub' Commands:
  9248.      subsubsection.
  9249. `@subsubsection TITLE'
  9250.      Begin a subsubsection within a subsection.  In a printed manual,
  9251.      the subsubsection title is numbered and appears in the table of
  9252.      contents.  In Info, the title is underlined with periods.  *Note
  9253.      The `subsub' Commands: subsubsection.
  9254. `@subtitle TITLE'
  9255.      In a printed manual, set a subtitle in a normal sized font flush to
  9256.      the right-hand side of the page.  Not relevant to Info, which does
  9257.      not have title pages.  *Note `@title' `@subtitle' and `@author'
  9258.      Commands: title subtitle author.
  9259. `@summarycontents'
  9260.      Print a short table of contents.  Not relevant to Info, which uses
  9261.      menus rather than tables of contents.  A synonym for
  9262.      `@shortcontents'.  *Note Generating a Table of Contents: Contents.
  9263. `@syncodeindex FROM-INDEX INTO-INDEX'
  9264.      Merge the index named in the first argument into the index named in
  9265.      the second argument, printing the entries from the first index in
  9266.      `@code' font.  *Note Combining Indices::.
  9267. `@synindex FROM-INDEX INTO-INDEX'
  9268.      Merge the index named in the first argument into the index named in
  9269.      the second argument.  Do not change the font of FROM-INDEX
  9270.      entries.  *Note Combining Indices::.
  9271. `@t{TEXT}'
  9272.      Print TEXT in a fixed-width, typewriter-like font.  No effect in
  9273.      Info.  *Note Fonts::.
  9274. `@table FORMATTING-COMMAND'
  9275.      Begin a two-column table, using `@item' for each entry.  Write
  9276.      each first column entry on the same line as `@item'.  First column
  9277.      entries are printed in the font resulting from FORMATTING-COMMAND.
  9278.      Pair with `@end table'.  *Note Making a Two-column Table:
  9279.      Two-column Tables.  Also see *Note `@ftable' and `@vtable': ftable
  9280.      vtable, and *Note `@itemx': itemx.
  9281. `@TeX{}'
  9282.      Insert the logo TeX.  *Note Inserting TeX and (C): TeX and
  9283.      copyright.
  9284. `@tex'
  9285.      Enter TeX completely.  Pair with `@end tex'.  *Note Using Ordinary
  9286.      TeX Commands: Using Ordinary TeX Commands.
  9287. `@thischapter'
  9288.      In a heading or footing, stands for the number and name of the
  9289.      current chapter, in the format `Chapter 1: Title'.  *Note How to
  9290.      Make Your Own Headings: Custom Headings.
  9291. `@thischaptername'
  9292.      In a heading or footing, stands for the name of the current
  9293.      chapter.  *Note How to Make Your Own Headings: Custom Headings.
  9294. `@thisfile'
  9295.      In a heading or footing, stands for the name of the current
  9296.      `@include' file.  Does not insert anything if not within an
  9297.      `@include' file.  *Note How to Make Your Own Headings: Custom
  9298.      Headings.
  9299. `@thispage'
  9300.      In a heading or footing, stands for the current page number.
  9301.      *Note How to Make Your Own Headings: Custom Headings.
  9302. `@thistitle'
  9303.      In a heading or footing, stands for the name of the document, as
  9304.      specified by the `@settitle' command.  *Note How to Make Your Own
  9305.      Headings: Custom Headings.
  9306. `@tindex ENTRY'
  9307.      Add ENTRY to the index of data types.  *Note Defining the Entries
  9308.      of an Index: Index Entries.
  9309. `@title TITLE'
  9310.      In a printed manual, set a title flush to the left-hand side of the
  9311.      page in a larger than normal font and underline it with a black
  9312.      rule.  Not relevant to Info, which does not have title pages.
  9313.      *Note The `@title' `@subtitle' and `@author' Commands: title
  9314.      subtitle author.
  9315. `@titlefont{TEXT}'
  9316.      In a printed manual, print TEXT in a larger than normal font.  Not
  9317.      relevant to Info, which does not have title pages.  *Note The
  9318.      `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
  9319. `@titlepage'
  9320.      Indicate to Texinfo the beginning of the title page.  Write
  9321.      command on a line of its own.  Pair with `@end titlepage'.
  9322.      Nothing between `@titlepage' and `@end titlepage' appears in Info.
  9323.      *Note `@titlepage': titlepage.
  9324. `@today{}'
  9325.      Insert the current date, in `1 Jan 1900' style.  *Note How to Make
  9326.      Your Own Headings: Custom Headings.
  9327. `@top TITLE'
  9328.      In a Texinfo file to be formatted with `makeinfo', identify the
  9329.      topmost `@node' line in the file, which must be written on the line
  9330.      immediately preceding the `@top' command.  Used for `makeinfo''s
  9331.      node pointer insertion feature.  The title is underlined with
  9332.      asterisks.  Both the `@node' line and the `@top' line normally
  9333.      should be enclosed by `@ifinfo' and `@end ifinfo'.  In TeX and
  9334.      `texinfo-format-buffer', the `@top' command is merely a synonym
  9335.      for `@unnumbered'.  *Note Creating Pointers with `makeinfo':
  9336.      makeinfo Pointer Creation.
  9337. `@unnumbered TITLE'
  9338.      In a printed manual, begin a chapter that appears without chapter
  9339.      numbers of any kind.  The title appears in the table of contents
  9340.      of a printed manual.  In Info, the title is underlined with
  9341.      asterisks.  *Note `@unnumbered' and `@appendix': unnumbered &
  9342.      appendix.
  9343. `@unnumberedsec TITLE'
  9344.      In a printed manual, begin a section that appears without section
  9345.      numbers of any kind.  The title appears in the table of contents
  9346.      of a printed manual.  In Info, the title is underlined with equal
  9347.      signs.  *Note Section Commands: unnumberedsec appendixsec heading.
  9348. `@unnumberedsubsec TITLE'
  9349.      In a printed manual, begin an unnumbered subsection within a
  9350.      chapter.  The title appears in the table of contents of a printed
  9351.      manual.  In Info, the title is underlined with hyphens.  *Note
  9352.      `@unnumberedsubsec' `@appendixsubsec' `@subheading':
  9353.      unnumberedsubsec appendixsubsec subheading.
  9354. `@unnumberedsubsubsec TITLE'
  9355.      In a printed manual, begin an unnumbered subsubsection within a
  9356.      chapter.  The title appears in the table of contents of a printed
  9357.      manual.  In Info, the title is underlined with periods.  *Note The
  9358.      `subsub' Commands: subsubsection.
  9359. `@value{FLAG}'
  9360.      Replace FLAG with the value to which it is set by `@set FLAG'.
  9361.      *Note `@set' `@clear' `@value': set clear value.
  9362. `@var{METASYNTACTIC-VARIABLE}'
  9363.      Highlight a metasyntactic variable, which is something that stands
  9364.      for another piece of text.  *Note Indicating Metasyntactic
  9365.      Variables: var.
  9366. `@vindex ENTRY'
  9367.      Add ENTRY to the index of variables.  *Note Defining the Entries
  9368.      of an Index: Index Entries.
  9369. `@vskip AMOUNT'
  9370.      In a printed manual, insert whitespace so as to push text on the
  9371.      remainder of the page towards the bottom of the page.  Used in
  9372.      formatting the copyright page with the argument `0pt plus 1filll'.
  9373.      (Note spelling of `filll'.)  `@vskip' may be used only in
  9374.      contexts ignored for Info.  *Note The Copyright Page and Printed
  9375.      Permissions: Copyright & Permissions.
  9376. `@vtable FORMATTING-COMMAND'
  9377.      Begin a two-column table, using `@item' for each entry.
  9378.      Automatically enter each of the items in the first column into the
  9379.      index of variables.  Pair with `@end vtable'.  The same as
  9380.      `@table', except for indexing.  *Note `@ftable' and `@vtable':
  9381.      ftable vtable.
  9382. `@w{TEXT}'
  9383.      Prevent TEXT from being split across two lines.  Do not end a
  9384.      paragraph that uses `@w' with an `@refill' command.  In the
  9385.      Texinfo file, keep TEXT on one line.  *Note `@w': w.
  9386. `@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  9387.      Make a reference that starts with `See' in a printed manual.
  9388.      Follow command with a punctuation mark.  Only the first argument is
  9389.      mandatory.  *Note `@xref': xref.
  9390. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  9391. file texi.texi.
  9392.    This file documents Texinfo, a documentation system that uses a
  9393. single source file to produce both on-line information and a printed
  9394. manual.
  9395.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  9396.    This is the second edition of the Texinfo documentation,
  9397. and is consistent with version 2 of `texinfo.tex'.
  9398.    Permission is granted to make and distribute verbatim copies of this
  9399. manual provided the copyright notice and this permission notice are
  9400. preserved on all copies.
  9401.    Permission is granted to copy and distribute modified versions of
  9402. this manual under the conditions for verbatim copying, provided that
  9403. the entire resulting derived work is distributed under the terms of a
  9404. permission notice identical to this one.
  9405.    Permission is granted to copy and distribute translations of this
  9406. manual into another language, under the above conditions for modified
  9407. versions, except that this permission notice may be stated in a
  9408. translation approved by the Free Software Foundation.
  9409. File: texi.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top
  9410. Tips and Hints
  9411. **************
  9412.    Here are some tips for writing Texinfo documentation:
  9413.    * Write in the present tense, not in the past or the future.
  9414.    * Write actively!  For example, write "We recommend that ..." rather
  9415.      than "It is recommended that ...".
  9416.    * Use 70 or 72 as your fill column.  Longer lines are hard to read.
  9417.    * Include a copyright notice and copying permissions.
  9418. Index, index, index!
  9419. ....................
  9420.    Write many index entries, in different ways.  Readers like indices;
  9421. they are helpful and convenient.
  9422.    Although it is easiest to write index entries as you write the body
  9423. of the text, some people prefer to write entries afterwards.  In either
  9424. case, write an entry before the paragraph to which it applies.  This
  9425. way, an index entry points to the first page of a paragraph that is
  9426. split across pages.
  9427.    Here are more hints we have found valuable:
  9428.    * Write each index entry differently, so each entry refers to a
  9429.      different place in the document.  The index of an Info file lists
  9430.      only one location for each entry.
  9431.    * Write index entries only where a topic is discussed significantly.
  9432.      For example, it is not useful to index "debugging information" in
  9433.      a chapter on reporting bugs.  Someone who wants to know about
  9434.      debugging information will certainly not find it in that chapter.
  9435.    * Consistently capitalize the first word of every index entry, or
  9436.      else use lower case.  According to convention, you should
  9437.      capitalize the first word of an index entry.  However, this
  9438.      practice may make an index look crowded.  Some writers prefer
  9439.      lower case.  Regardless of which you prefer, choose one style and
  9440.      stick to it.  Mixing the two styles looks bad.
  9441.    * Always capitalize or use upper case for those words in an index for
  9442.      which this is proper, such as names of countries or acronyms.
  9443.    * Write the indexing commands that refer to a whole section
  9444.      immediately after the section command, and write the indexing
  9445.      commands that refer to the paragraph before the paragraph.
  9446.      In the example that follows, a blank line comes after the index
  9447.      entry for "Leaping":
  9448.           @section The Dog and the Fox
  9449.           @cindex Jumping, in general
  9450.           @cindex Leaping
  9451.           
  9452.           @cindex Dog, lazy, jumped over
  9453.           @cindex Lazy dog jumped over
  9454.           @cindex Fox, jumps over dog
  9455.           @cindex Quick fox jumps over dog
  9456.           The quick brown fox jumps over the lazy dog.
  9457.      (Note that the example shows entries for the same concept that are
  9458.      written in different ways--`Lazy dog', and `Dog, lazy'--so readers
  9459.      can look up the concept in different ways.)
  9460. Blank lines
  9461. ...........
  9462.    * Insert a blank line between a sectioning command and the first
  9463.      following sentence or paragraph, or between the indexing commands
  9464.      associated with the sectioning command and the first following
  9465.      sentence or paragraph, as shown in the tip on indexing.
  9466.      Otherwise, a formatter may fold title and paragraph together.
  9467.    * Always insert a blank line before an `@table' command and after an
  9468.      `@end table' command; but never insert a blank line after an
  9469.      `@table' command or before an `@end table' command.
  9470.      For example,
  9471.           Types of fox:
  9472.           
  9473.           @table @samp
  9474.           @item Quick
  9475.           Jump over lazy dogs.
  9476.           
  9477.           @item Brown
  9478.           Also jump over lazy dogs.
  9479.           @end table
  9480.           @noindent
  9481.           On the other hand, ...
  9482.      Insert blank lines before and after `@itemize' ... `@end itemize'
  9483.      and `@enumerate' ... `@end enumerate' in the same way.
  9484. Complete phrases
  9485. ................
  9486.    Complete phrases are easier to read than ...
  9487.    * Write entries in an itemized list as complete sentences; or at
  9488.      least, as complete phrases.  Incomplete expressions ... awkward
  9489.      ... like this.
  9490.    * Write the prefatory sentence or phrase for a multi-item list or
  9491.      table as a complete expression.  Do not write "You can set:";
  9492.      instead, write "You can set these variables:".  The former
  9493.      expression sounds cut off.
  9494. Editions, dates and versions
  9495. ............................
  9496.    Write the edition and version numbers and date in three places in
  9497. every manual:
  9498.   1. In the first `@ifinfo' section, for people reading the Texinfo
  9499.      file.
  9500.   2. In the `@titlepage' section, for people reading the printed manual.
  9501.   3. In the `Top' node, for people reading the Info file.
  9502. Also, it helps to write a note before the first `@ifinfo' section to
  9503. explain what you are doing.
  9504. For example:
  9505.      @c ===> NOTE! <==
  9506.      @c Specify the edition and version numbers and date
  9507.      @c in *three* places:
  9508.      @c   1. First ifinfo section  2. title page  3. top node
  9509.      @c To find the locations, search for !!set
  9510.      
  9511.      @ifinfo
  9512.      @c !!set edition, date, version
  9513.      This is Edition 4.03, January 1992,
  9514.      of the @cite{GDB Manual} for GDB Version 4.3.
  9515.      ...
  9516. --or use `@set' and `@value' (*note `@value' Example: value Example.).
  9517. Definition Commands
  9518. ...................
  9519.    Definition commands are `@deffn', `@defun', `@defmac', and the like,
  9520. and enable you to write descriptions in a uniform format.
  9521.    * Write just one definition command for each entity you define with a
  9522.      definition command.  The automatic indexing feature creates an
  9523.      index entry that leads the reader to the definition.
  9524.    * Use `@table' ... `@end table' in an appendix that contains a
  9525.      summary of functions, not `@deffn' or other definition commands.
  9526. Capitalization
  9527. ..............
  9528.    * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
  9529.      in upper case.
  9530.    * Capitalize `Info'; it is a name.
  9531.    * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
  9532.      `X'.  This command causes the formatters to typeset the name
  9533.      according to the wishes of Donald Knuth, who wrote TeX.
  9534. Spaces
  9535. ......
  9536.    Do not use spaces to format a Texinfo file, except inside of
  9537. `@example' ... `@end example' and similar commands.
  9538.    For example, TeX fills the following:
  9539.          @kbd{C-x v}
  9540.          @kbd{M-x vc-next-action}
  9541.             Perform the next logical operation
  9542.             on the version-controlled file
  9543.             corresponding to the current buffer.
  9544. so it looks like this:
  9545.      `C-x v' `M-x vc-next-action' Perform the next logical operation on
  9546.      the version-controlled file corresponding to the current buffer.
  9547. In this case, the text should be formatted with `@table', `@item', and
  9548. `@itemx', to create a table.
  9549. @code, @samp, @var, and `---'
  9550. .............................
  9551.    * Use `@code' around Lisp symbols, including command names.  For
  9552.      example,
  9553.           The main function is @code{vc-next-action}, ...
  9554.    * Avoid putting letters such as `s' immediately after an `@code'.
  9555.      Such letters look bad.
  9556.    * Use `@var' around meta-variables.  Do not write angle brackets
  9557.      around them.
  9558.    * Use three hyphens in a row, `---', to indicate a long dash.  TeX
  9559.      typesets these as a long dash and the Info formatters reduce three
  9560.      hyphens to two.
  9561. Periods Outside of Quotes
  9562. .........................
  9563.    Place periods and other punctuation marks *outside* of quotations,
  9564. unless the punctuation is part of the quotation.  This practice goes
  9565. against convention, but enables the reader to distinguish between the
  9566. contents of the quotation and the whole passage.
  9567.    For example, you should write the following sentence with the period
  9568. outside the end quotation marks:
  9569.      Evidently, `au' is an abbreviation for ``author''.
  9570. since `au' does *not* serve as an  abbreviation for `author.' (with a
  9571. period following the word).
  9572. Introducing New Terms
  9573. .....................
  9574.    * Introduce new terms so that a user who does not know them can
  9575.      understand them from context; or write a definition for the term.
  9576.      For example, in the following, the terms "check in", "register" and
  9577.      "delta" are all appearing for the first time; the example sentence
  9578.      should be rewritten so they are understandable.
  9579.           The major function assists you in checking in a file to your
  9580.           version control system and registering successive sets of
  9581.           changes to it as deltas.
  9582.    * Use the `@dfn' command around a word being introduced, to indicate
  9583.      that the user should not expect to know the meaning already, and
  9584.      should expect to learn the meaning from this passage.
  9585. @pxref
  9586. ......
  9587.    Absolutely never use `@pxref' except in the special context for
  9588. which it is designed: inside parentheses, with the closing parenthesis
  9589. following immediately after the closing brace.  One formatter
  9590. automatically inserts closing punctuation and the other does not.  This
  9591. means that the output looks right both in printed output and in an Info
  9592. file, but only when the command is used inside parentheses.
  9593. Invoking from a Shell
  9594. .....................
  9595.    You can invoke programs such as Emacs, GCC, and GAWK from a shell.
  9596. The documentation for each program should contain a section that
  9597. describes this.  Unfortunately, if the node names and titles for these
  9598. sections are all different, readers find it hard to search for the
  9599. section.
  9600.    Name such sections with a phrase beginning with the word
  9601. `Invoking ...', as in `Invoking Emacs'; this way users can find the
  9602. section easily.
  9603. ANSI C Syntax
  9604. .............
  9605.    When you use `@example' to describe a C function's calling
  9606. conventions, use the ANSI C syntax, like this:
  9607.      void dld_init (char *@var{path});
  9608. And in the subsequent discussion, refer to the argument values by
  9609. writing the same argument names, again highlighted with `@var'.
  9610.    Avoid the obsolete style that looks like this:
  9611.      #include <dld.h>
  9612.      
  9613.      dld_init (path)
  9614.      char *path;
  9615.    Also, it is best to avoid writing `#include' above the declaration
  9616. just to indicate that the function is declared in a header file.  The
  9617. practice may give the misimpression that the `#include' belongs near
  9618. the declaration of the function.  Either state explicitly which header
  9619. file holds the declaration or, better yet, name the header file used
  9620. for a group of functions at the beginning of the section that describes
  9621. the functions.
  9622. Bad Examples
  9623. ............
  9624.    Here are several examples of bad writing to avoid:
  9625.    In this example, say, " ... you must `@dfn'{check in} the new
  9626. version."  That flows better.
  9627.      When you are done editing the file, you must perform a
  9628.      `@dfn'{check in}.
  9629.    In the following example, say, "... makes a unified interface such
  9630. as VC mode possible."
  9631.      SCCS, RCS and other version-control systems all perform similar
  9632.      functions in broadly similar ways (it is this resemblance which
  9633.      makes a unified control mode like this possible).
  9634.    And in this example, you should specify what `it' refers to:
  9635.      If you are working with other people, it assists in coordinating
  9636.      everyone's changes so they do not step on each other.
  9637. And Finally ...
  9638. ...............
  9639.    * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
  9640.      in the name `Bach'.  But pronounce Texinfo as in `speck':
  9641.      `teckinfo'.
  9642.    * Write notes for yourself at the very end of a Texinfo file after
  9643.      the `@bye'.  None of the formatters process text after the `@bye';
  9644.      it is as if the text were within `@ignore' ...  `@end ignore'.
  9645. File: texi.info,  Node: Sample Texinfo File,  Next: Sample Permissions,  Prev: Tips,  Up: Top
  9646. A Sample Texinfo File
  9647. *********************
  9648.    Here is a complete, short sample Texinfo file, without any
  9649. commentary.  You can see this file, with comments, in the first chapter.
  9650. *Note A Short Sample Texinfo File: Short Sample.
  9651.      \input texinfo   @c -*-texinfo-*-
  9652.      @c %**start of header
  9653.      @setfilename sample.info
  9654.      @settitle Sample Document
  9655.      @c %**end of header
  9656.      
  9657.      @setchapternewpage odd
  9658.      
  9659.      @ifinfo
  9660.      This is a short example of a complete Texinfo file.
  9661.      
  9662.      Copyright 1990 Free Software Foundation, Inc.
  9663.      @end ifinfo
  9664.      
  9665.      @titlepage
  9666.      @sp 10
  9667.      @comment The title is printed in a large font.
  9668.      @center @titlefont{Sample Title}
  9669.      
  9670.      @c The following two commands start the copyright page.
  9671.      @page
  9672.      @vskip 0pt plus 1filll
  9673.      Copyright @copyright{} 1990 Free Software Foundation, Inc.
  9674.      @end titlepage
  9675.      
  9676.      @node    Top,       First Chapter, (dir),    (dir)
  9677.      @comment node-name, next,          previous, up
  9678.      
  9679.      @menu
  9680.      * First Chapter::    The first chapter is the
  9681.                           only chapter in this sample.
  9682.      * Concept Index::    This index has two entries.
  9683.      @end menu
  9684.      
  9685.      @node    First Chapter, Concept Index, Top,      Top
  9686.      @comment node-name,     next,          previous, up
  9687.      @chapter First Chapter
  9688.      @cindex Sample index entry
  9689.      
  9690.      This is the contents of the first chapter.
  9691.      @cindex Another sample index entry
  9692.      
  9693.      Here is a numbered list.
  9694.      
  9695.      @enumerate
  9696.      @item
  9697.      This is the first item.
  9698.      
  9699.      @item
  9700.      This is the second item.
  9701.      @end enumerate
  9702.      
  9703.      The @code{makeinfo} and @code{texinfo-format-buffer}
  9704.      commands transform a Texinfo file such as this into
  9705.      an Info file; and @TeX{} typesets it for a printed
  9706.      manual.
  9707.      
  9708.      @node    Concept Index,    ,  First Chapter, Top
  9709.      @comment node-name,    next,  previous,      up
  9710.      @unnumbered Concept Index
  9711.      
  9712.      @printindex cp
  9713.      
  9714.      @contents
  9715.      @bye
  9716. File: texi.info,  Node: Sample Permissions,  Next: Include Files,  Prev: Sample Texinfo File,  Up: Top
  9717. Sample Permissions
  9718. ******************
  9719.    Texinfo files should contain sections that tell the readers that they
  9720. have the right to copy and distribute the Texinfo file, the Info file,
  9721. and the printed manual.
  9722.    Also, if you are writing a manual about software, you should explain
  9723. that the software is free and either include the GNU General Public
  9724. License (GPL) or provide a reference to it.  *Note Distribution:
  9725. (emacs)Distrib, for an example of the text that could be used in the
  9726. software "Distribution", "General Public License", and "NO WARRANTY"
  9727. sections of a document.  *Note Texinfo Copying Conditions: Copying, for
  9728. an example of a brief explanation of how the copying conditions provide
  9729. you with rights.
  9730. * Menu:
  9731. * Inserting Permissions::       How to put permissions in your document.
  9732. * ifinfo Permissions::          Sample `ifinfo' copying permissions.
  9733. * Titlepage Permissions::       Sample Titlepage copying permissions.
  9734. File: texi.info,  Node: Inserting Permissions,  Next: ifinfo Permissions,  Up: Sample Permissions
  9735. Inserting Permissions
  9736. =====================
  9737.    In a Texinfo file, the first `@ifinfo' section usually begins with a
  9738. line that says what the file documents.  This is what a person reading
  9739. the unprocessed Texinfo file or using the advanced Info command `g *'
  9740. sees first.  *note Advanced Info commands: (info)Expert, for more
  9741. information. (A reader using the regular Info commands usually starts
  9742. reading at the first node and skips this first section, which is not in
  9743. a node.)
  9744.    In the `@ifinfo' section, the summary sentence is followed by a
  9745. copyright notice and then by the copying permission notice.  One of the
  9746. copying permission paragraphs is enclosed in `@ignore' and `@end
  9747. ignore' commands.  This paragraph states that the Texinfo file can be
  9748. processed through TeX and printed, provided the printed manual carries
  9749. the proper copying permission notice.  This paragraph is not made part
  9750. of the Info file since it is not relevant to the Info file; but it is a
  9751. mandatory part of the Texinfo file since it permits people to process
  9752. the Texinfo file in TeX and print the results.
  9753.    In the printed manual, the Free Software Foundation copying
  9754. permission notice follows the copyright notice and publishing
  9755. information and is located within the region delineated by the
  9756. `@titlepage' and `@end titlepage' commands.  The copying permission
  9757. notice is exactly the same as the notice in the `@ifinfo' section
  9758. except that the paragraph enclosed in `@ignore' and `@end ignore'
  9759. commands is not part of the notice.
  9760.    To make it simple to insert a permission notice into each section of
  9761. the Texinfo file, sample permission notices for each section are
  9762. reproduced in full below.
  9763.    Note that you may need to specify the correct name of a section
  9764. mentioned in the permission notice.  For example, in `The GDB Manual',
  9765. the name of the section referring to the General Public License is
  9766. called the "GDB General Public License", but in the sample shown below,
  9767. that section is referred to generically as the "GNU General Public
  9768. License".  If the Texinfo file does not carry a copy of the General
  9769. Public License, leave out the reference to it, but be sure to include
  9770. the rest of the sentence.
  9771. File: texi.info,  Node: ifinfo Permissions,  Next: Titlepage Permissions,  Prev: Inserting Permissions,  Up: Sample Permissions
  9772. `ifinfo' Copying Permissions
  9773. ============================
  9774.    In the `@ifinfo' section of a Texinfo file, the standard Free
  9775. Software Foundation permission notice reads as follows:
  9776.      This file documents ...
  9777.      
  9778.      Copyright 1992 Free Software Foundation, Inc.
  9779.      
  9780.      Permission is granted to make and distribute verbatim
  9781.      copies of this manual provided the copyright notice and
  9782.      this permission notice are preserved on all copies.
  9783.      
  9784.      @ignore
  9785.      Permission is granted to process this file through TeX
  9786.      and print the results, provided the printed document
  9787.      carries a copying permission notice identical to this
  9788.      one except for the removal of this paragraph (this
  9789.      paragraph not being relevant to the printed manual).
  9790.      
  9791.      @end ignore
  9792.      Permission is granted to copy and distribute modified
  9793.      versions of this manual under the conditions for
  9794.      verbatim copying, provided also that the sections
  9795.      entitled ``Copying'' and ``GNU General Public License''
  9796.      are included exactly as in the original, and provided
  9797.      that the entire resulting derived work is distributed
  9798.      under the terms of a permission notice identical to this
  9799.      one.
  9800.      
  9801.      Permission is granted to copy and distribute
  9802.      translations of this manual into another language,
  9803.      under the above conditions for modified versions,
  9804.      except that this permission notice may be stated in a
  9805.      translation approved by the Free Software Foundation.
  9806. File: texi.info,  Node: Titlepage Permissions,  Prev: ifinfo Permissions,  Up: Sample Permissions
  9807. Titlepage Copying Permissions
  9808. =============================
  9809.    In the `@titlepage' section of a Texinfo file, the standard Free
  9810. Software Foundation copying permission notice follows the copyright
  9811. notice and publishing information.  The standard phrasing is as follows:
  9812.      Permission is granted to make and distribute verbatim
  9813.      copies of this manual provided the copyright notice and
  9814.      this permission notice are preserved on all copies.
  9815.      
  9816.      Permission is granted to copy and distribute modified
  9817.      versions of this manual under the conditions for
  9818.      verbatim copying, provided also that the sections
  9819.      entitled ``Copying'' and ``GNU General Public License''
  9820.      are included exactly as in the original, and provided
  9821.      that the entire resulting derived work is distributed
  9822.      under the terms of a permission notice identical to this
  9823.      one.
  9824.      
  9825.      Permission is granted to copy and distribute
  9826.      translations of this manual into another language,
  9827.      under the above conditions for modified versions,
  9828.      except that this permission notice may be stated in a
  9829.      translation approved by the Free Software Foundation.
  9830. File: texi.info,  Node: Include Files,  Next: Headings,  Prev: Sample Permissions,  Up: Top
  9831. Include Files
  9832. *************
  9833.    When TeX or an Info formatting command sees an `@include' command in
  9834. a Texinfo file, it processes the contents of the file named by the
  9835. command and incorporates them into the DVI or Info file being created.
  9836. Index entries from the included file are incorporated into the indices
  9837. of the output file.
  9838.    Include files let you keep a single large document as a collection of
  9839. conveniently small parts.
  9840. * Menu:
  9841. * Using Include Files::         How to use the `@include' command.
  9842. * texinfo-multiple-files-update::  How to create and update nodes and
  9843.                                   menus when using included files.
  9844. * Include File Requirements::   What `texinfo-multiple-files-update' expects.
  9845. * Sample Include File::         A sample outer file with included files
  9846.                                   within it; and a sample included file.
  9847. * Include Files Evolution::     How use of the `@include' command
  9848.                                   has changed over time.
  9849. File: texi.info,  Node: Using Include Files,  Next: texinfo-multiple-files-update,  Up: Include Files
  9850. How to Use Include Files
  9851. ========================
  9852.    To include another file within a Texinfo file, write the `@include'
  9853. command at the beginning of a line and follow it on the same line by
  9854. the name of a file to be included.  For example:
  9855.      @include buffers.texi
  9856.    An included file should simply be a segment of text that you expect
  9857. to be included as is into the overall or "outer" Texinfo file; it
  9858. should not contain the standard beginning and end parts of a Texinfo
  9859. file.  In particular, you should not start an included file with a line
  9860. saying `\input texinfo'; if you do, that phrase is inserted into the
  9861. output file as is.  Likewise, you should not end an included file with
  9862. an `@bye' command; nothing after `@bye' is formatted.
  9863.    In the past, you were required to write an `@setfilename' line at the
  9864. beginning of an included file, but no longer.  Now, it does not matter
  9865. whether you write such a line.  If an `@setfilename' line exists in an
  9866. included file, it is ignored.
  9867.    Conventionally, an included file begins with an `@node' line that is
  9868. followed by an `@chapter' line.  Each included file is one chapter.
  9869. This makes it easy to use the regular node and menu creating and
  9870. updating commands to create the node pointers and menus within the
  9871. included file.  However, the simple Emacs node and menu creating and
  9872. updating commands do not work with multiple Texinfo files.  Thus you
  9873. cannot use these commands to fill in the `Next', `Previous', and `Up'
  9874. pointers of the `@node' line that begins the included file.  Also, you
  9875. cannot use the regular commands to create a master menu for the whole
  9876. file.  Either you must insert the menus and the `Next', `Previous', and
  9877. `Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
  9878. command, `texinfo-multiple-files-update', that is designed for
  9879. `@include' files.
  9880. File: texi.info,  Node: texinfo-multiple-files-update,  Next: Include File Requirements,  Prev: Using Include Files,  Up: Include Files
  9881. `texinfo-multiple-files-update'
  9882. ===============================
  9883.    GNU Emacs Texinfo mode provides a command to handle included files
  9884. called `texinfo-multiple-files-update'.  This command creates or
  9885. updates `Next', `Previous', and `Up' pointers of included files as well
  9886. as those in the outer or overall Texinfo file, and it creates or
  9887. updates a main menu in the outer file.  Depending whether you call it
  9888. with optional arguments, the command updates only the pointers in the
  9889. first `@node' line of the included files or all of them:
  9890. `M-x texinfo-multiple-files-update'
  9891.      Called without any arguments:
  9892.         - Create or update the `Next', `Previous', and `Up' pointers of
  9893.           the first `@node' line in each file included in an outer or
  9894.           overall Texinfo file.
  9895.         - Create or update the `Top' level node pointers of the outer or
  9896.           overall file.
  9897.         - Create or update a main menu in the outer file.
  9898. `C-u M-x texinfo-multiple-files-update'
  9899.      Called with `C-u' as a prefix argument:
  9900.         - Create or update pointers in the first `@node' line in each
  9901.           included file.
  9902.         - Create or update the `Top' level node pointers of the outer
  9903.           file.
  9904.         - Create and insert a master menu in the outer file.  The
  9905.           master menu is made from all the menus in all the included
  9906.           files.
  9907. `C-u 8 M-x texinfo-multiple-files-update'
  9908.      Called with a numeric prefix argument, such as `C-u 8':
  9909.         - Create or update *all* the `Next', `Previous', and `Up'
  9910.           pointers of all the included files.
  9911.         - Create or update *all* the menus of all the included files.
  9912.         - Create or update the `Top' level node pointers of the outer or
  9913.           overall file.
  9914.         - And then create a master menu in the outer file.  This is
  9915.           similar to invoking `texinfo-master-menu' with an argument
  9916.           when you are working with just one file.
  9917.    Note the use of the prefix argument in interactive use: with a
  9918. regular prefix argument, just `C-u', the
  9919. `texinfo-multiple-files-update' command inserts a master menu; with a
  9920. numeric prefix argument, such as `C-u 8', the command updates *every*
  9921. pointer and menu in *all* the files and then inserts a master menu.
  9922. File: texi.info,  Node: Include File Requirements,  Next: Sample Include File,  Prev: texinfo-multiple-files-update,  Up: Include Files
  9923. Include File Requirements
  9924. =========================
  9925.    If you plan to use the `texinfo-multiple-files-update' command, the
  9926. outer Texinfo file that lists included files within it should contain
  9927. nothing but the beginning and end parts of a Texinfo file, and a number
  9928. of `@include' commands listing the included files.  It should not even
  9929. include indices, which should be listed in an included file of their
  9930.    Moreover, each of the included files must contain exactly one highest
  9931. level node (conventionally, `@chapter' or equivalent), and this node
  9932. must be the first node in the included file.  Furthermore, each of
  9933. these highest level nodes in each included file must be at the same
  9934. hierarchical level in the file structure.  Usually, each is an
  9935. `@chapter', an `@appendix', or an `@unnumbered' node.  Thus, normally,
  9936. each included file contains one, and only one, chapter or
  9937. equivalent-level node.
  9938.    The outer file should contain only *one* node, the `Top' node.  It
  9939. should *not* contain any nodes besides the single `Top' node.  The
  9940. `texinfo-multiple-files-update' command will not process them.
  9941. File: texi.info,  Node: Sample Include File,  Next: Include Files Evolution,  Prev: Include File Requirements,  Up: Include Files
  9942. Sample File with `@include'
  9943. ===========================
  9944.    Here is an example of a complete outer Texinfo file with `@include'
  9945. files within it before running `texinfo-multiple-files-update', which
  9946. would insert a main or master menu:
  9947.      \input texinfo @c -*-texinfo-*-
  9948.      @setfilename  include-example.info
  9949.      @settitle Include Example
  9950.      
  9951.      @setchapternewpage odd
  9952.      @titlepage
  9953.      @sp 12
  9954.      @center @titlefont{Include Example}
  9955.      @sp 2
  9956.      @center by Whom Ever
  9957.      
  9958.      @page
  9959.      @vskip 0pt plus 1filll
  9960.      Copyright @copyright{} 1990 Free Software Foundation, Inc.
  9961.      @end titlepage
  9962.      
  9963.      @ifinfo
  9964.      @node Top, First, (dir), (dir)
  9965.      @top Master Menu
  9966.      @end ifinfo
  9967.      
  9968.      @include foo.texinfo
  9969.      @include bar.texinfo
  9970.      @include concept-index.texinfo
  9971.      
  9972.      @summarycontents
  9973.      @contents
  9974.      
  9975.      @bye
  9976.    An included file, such as `foo.texinfo', might look like this:
  9977.      @node First, Second, , Top
  9978.      @chapter First Chapter
  9979.      
  9980.      Contents of first chapter ...
  9981.    The full contents of `concept-index.texinfo' might be as simple as
  9982. this:
  9983.      @node Concept Index, , Second, Top
  9984.      @unnumbered Concept Index
  9985.      
  9986.      @printindex cp
  9987.    The outer Texinfo source file for `The GNU Emacs Lisp Reference
  9988. Manual' is named `elisp.texi'.  This outer file contains a master menu
  9989. with 417 entries and a list of 41 `@include' files.
  9990. File: texi.info,  Node: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files
  9991. Evolution of Include Files
  9992. ==========================
  9993.    When Info was first created, it was customary to create many small
  9994. Info files on one subject.  Each Info file was formatted from its own
  9995. Texinfo source file.  This custom meant that Emacs did not need to make
  9996. a large buffer to hold the whole of a large Info file when someone
  9997. wanted information; instead, Emacs allocated just enough memory for the
  9998. small Info file that contained the particular information sought.  This
  9999. way, Emacs could avoid wasting memory.
  10000.    References from one file to another were made by referring to the
  10001. file name as well as the node name. (*Note Referring to Other Info
  10002. Files: Other Info Files.  Also, see *Note `@xref' with Four and Five
  10003. Arguments: Four and Five Arguments.)
  10004.    Include files were designed primarily as a way to create a single,
  10005. large printed manual out of several smaller Info files.  In a printed
  10006. manual, all the references were within the same document, so TeX could
  10007. automatically determine the references' page numbers.  The Info
  10008. formatting commands used include files only for creating joint indices;
  10009. each of the individual Texinfo files had to be formatted for Info
  10010. individually.  (Each, therefore, required its own `@setfilename' line.)
  10011.    However, because large Info files are now split automatically, it is
  10012. no longer necessary to keep them small.
  10013.    Nowadays, multiple Texinfo files are used mostly for large documents,
  10014. such as `The GNU Emacs Lisp Reference Manual', and for projects in
  10015. which several different people write different sections of a document
  10016. simultaneously.
  10017.    In addition, the Info formatting commands have been extended to work
  10018. with the `@include' command so as to create a single large Info file
  10019. that is split into smaller files if necessary.  This means that you can
  10020. write menus and cross references without naming the different Texinfo
  10021. files.
  10022. File: texi.info,  Node: Headings,  Next: Catching Mistakes,  Prev: Include Files,  Up: Top
  10023. Page Headings
  10024. *************
  10025.    Most printed manuals contain headings along the top of every page
  10026. except the title and copyright pages.  Some manuals also contain
  10027. footings.  (Headings and footings have no meaning to Info, which is not
  10028. paginated.)
  10029. * Menu:
  10030. * Headings Introduced::         Conventions for using page headings.
  10031. * Heading Format::              Standard page heading formats.
  10032. * Heading Choice::              How to specify the type of page heading.
  10033. * Custom Headings::             How to create your own headings and footings.
  10034. File: texi.info,  Node: Headings Introduced,  Next: Heading Format,  Up: Headings
  10035. Headings Introduced
  10036. ===================
  10037.    Texinfo provides standard page heading formats for manuals that are
  10038. printed on one side of each sheet of paper and for manuals that are
  10039. printed on both sides of the paper.  Usually, you will use one or other
  10040. of these formats, but you can specify your own format, if you wish.
  10041.    In addition, you can specify whether chapters should begin on a new
  10042. page, or merely continue the same page as the previous chapter; and if
  10043. chapters begin on new pages, you can specify whether they must be
  10044. odd-numbered pages.
  10045.    By convention, a book is printed on both sides of each sheet of
  10046. paper.  When you open a book, the right-hand page is odd-numbered, and
  10047. chapters begin on right-hand pages--a preceding left-hand page is left
  10048. blank if necessary.  Reports, however, are often printed on just one
  10049. side of paper, and chapters begin on a fresh page immediately following
  10050. the end of the preceding chapter.  In short or informal reports,
  10051. chapters often do not begin on a new page at all, but are separated
  10052. from the preceding text by a small amount of whitespace.
  10053.    The `@setchapternewpage' command controls whether chapters begin on
  10054. new pages, and whether one of the standard heading formats is used.  In
  10055. addition, Texinfo has several heading and footing commands that you can
  10056. use to generate your own heading and footing formats.
  10057.    In Texinfo, headings and footings are single lines at the tops and
  10058. bottoms of pages; you cannot create multiline headings or footings.
  10059. Each header or footer line is divided into three parts: a left part, a
  10060. middle part, and a right part.  Any part, or a whole line, may be left
  10061. blank.  Text for the left part of a header or footer line is set
  10062. flushleft; text for the middle part is centered; and, text for the
  10063. right part is set flushright.
  10064. File: texi.info,  Node: Heading Format,  Next: Heading Choice,  Prev: Headings Introduced,  Up: Headings
  10065. Standard Heading Formats
  10066. ========================
  10067.    Texinfo provides two standard heading formats, one for manuals
  10068. printed on one side of each sheet of paper, and the other for manuals
  10069. printed on both sides of the paper.
  10070.    By default, nothing is specified for the footing of a Texinfo file,
  10071. so the footing remains blank.
  10072.    The standard format for single-sided printing consists of a header
  10073. line in which the left-hand part contains the name of the chapter, the
  10074. central part is blank, and the right-hand part contains the page number.
  10075.    A single-sided page looks like this:
  10076.         _______________________
  10077.        |                       |
  10078.        | chapter   page number |
  10079.        |                       |
  10080.        | Start of text ...     |
  10081.        | ...                   |
  10082.        |                       |
  10083.    The standard format for two-sided printing depends on whether the
  10084. page number is even or odd.  By convention, even-numbered pages are on
  10085. the left- and odd-numbered pages are on the right.  (TeX will adjust the
  10086. widths of the left- and right-hand margins.  Usually, widths are
  10087. correct, but during double-sided printing, it is wise to check that
  10088. pages will bind properly--sometimes a printer will produce output in
  10089. which the even-numbered pages have a larger right-hand margin than the
  10090. odd-numbered pages.)
  10091.    In the standard double-sided format, the left part of the left-hand
  10092. (even-numbered) page contains the page number, the central part is
  10093. blank, and the right part contains the title (specified by the
  10094. `@settitle' command).  The left part of the right-hand (odd-numbered)
  10095. page contains the name of the chapter, the central part is blank, and
  10096. the right part contains the page number.
  10097.    Two pages, side by side as in an open book, look like this:
  10098.         _______________________     _______________________
  10099.        |                       |   |                       |
  10100.        | page number     title |   | chapter   page number |
  10101.        |                       |   |                       |
  10102.        | Start of text ...     |   | More  text ...        |
  10103.        | ...                   |   | ...                   |
  10104.        |                       |   |                       |
  10105. The chapter name is preceded by the word `Chapter', the chapter number
  10106. and a colon.  This makes it easier to keep track of where you are in
  10107. the manual.
  10108. File: texi.info,  Node: Heading Choice,  Next: Custom Headings,  Prev: Heading Format,  Up: Headings
  10109. Specifying the Type of Heading
  10110. ==============================
  10111.    TeX does not begin to generate page headings for a standard Texinfo
  10112. file until it reaches the `@end titlepage' command.  Thus, the title
  10113. and copyright pages are not numbered.  The `@end titlepage' command
  10114. causes TeX to begin to generate page headings according to a standard
  10115. format specified by the `@setchapternewpage' command that precedes the
  10116. `@titlepage' section.
  10117.    There are four possibilities:
  10118. No `@setchapternewpage' command
  10119.      Cause TeX to specify the single-sided heading format, with chapters
  10120.      on new pages. This is the same as `@setchapternewpage on'.
  10121. `@setchapternewpage on'
  10122.      Specify the single-sided heading format, with chapters on new
  10123.      pages.
  10124. `@setchapternewpage off'
  10125.      Cause TeX to start a new chapter on the same page as the last page
  10126.      of the preceding chapter, after skipping some vertical whitespace.
  10127.      Also cause TeX to typeset for single-sided printing.  (You can
  10128.      override the headers format with the `@headings double' command;
  10129.      see *Note The `@headings' Command: headings on off.)
  10130. `@setchapternewpage odd'
  10131.      Specify the double-sided heading format, with chapters on new
  10132.      pages.
  10133. Texinfo lacks an `@setchapternewpage even' command.
  10134. File: texi.info,  Node: Custom Headings,  Prev: Heading Choice,  Up: Headings
  10135. How to Make Your Own Headings
  10136. =============================
  10137.    You can use the standard headings provided with Texinfo or specify
  10138. your own.
  10139.    Texinfo provides six commands for specifying headings and footings.
  10140. The `@everyheading' command and `@everyfooting' command generate page
  10141. headers and footers that are the same for both even- and odd-numbered
  10142. pages.  The `@evenheading' command and `@evenfooting' command generate
  10143. headers and footers for even-numbered (left-hand) pages; and the
  10144. `@oddheading' command and `@oddfooting' command generate headers and
  10145. footers for odd-numbered (right-hand) pages.
  10146.    Write custom heading specifications in the Texinfo file immediately
  10147. after the `@end titlepage' command.  Enclose your specifications
  10148. between `@iftex' and `@end iftex' commands since the
  10149. `texinfo-format-buffer' command may not recognize them.  Also, you must
  10150. cancel the predefined heading commands with the `@headings off' command
  10151. before defining your own specifications.
  10152.    Here is how to tell TeX to place the chapter name at the left, the
  10153. page number in the center, and the date at the right of every header
  10154. for both even- and odd-numbered pages:
  10155.      @iftex
  10156.      @headings off
  10157.      @everyheading @thischapter @| @thispage @| @today{}
  10158.      @end iftex
  10159. You need to divide the left part from the central part and the central
  10160. part from the right had part by inserting `@|' between parts.
  10161. Otherwise, the specification command will not be able to tell where the
  10162. text for one part ends and the next part begins.
  10163.    Each part can contain text or @-commands.  The text is printed as if
  10164. the part were within an ordinary paragraph in the body of the page.
  10165. The @-commands replace themselves with the page number, date, chapter
  10166. name, or whatever.
  10167.    Here are the six heading and footing commands:
  10168. `@everyheading LEFT @| CENTER @| RIGHT'
  10169. `@everyfooting LEFT @| CENTER @| RIGHT'
  10170.      The `every' commands specify the format for both even- and
  10171.      odd-numbered pages.  These commands are for documents that are
  10172.      printed on one side of each sheet of paper, or for documents in
  10173.      which you want symmetrical headers or footers.
  10174. `@evenheading LEFT @| CENTER @| RIGHT'
  10175. `@oddheading  LEFT @| CENTER @| RIGHT'
  10176. `@evenfooting LEFT @| CENTER @| RIGHT'
  10177. `@oddfooting  LEFT @| CENTER @| RIGHT'
  10178.      The `even' and `odd' commands specify the format for even-numbered
  10179.      pages and odd-numbered pages.  These commands are for books and
  10180.      manuals that are printed on both sides of each sheet of paper.
  10181.    Use the `@this...' series of @-commands to provide the names of
  10182. chapters and sections and the page number.  You can use the `@this...'
  10183. commands in the left, center, or right portions of headers and footers,
  10184. or anywhere else in a Texinfo file so long as they are between `@iftex'
  10185. and `@end iftex' commands.
  10186.    Here are the `@this...' commands:
  10187. `@thispage'
  10188.      Expands to the current page number.
  10189. `@thischaptername'
  10190.      Expands to the name of the current chapter.
  10191. `@thischapter'
  10192.      Expands to the number and name of the current chapter, in the
  10193.      format `Chapter 1: Title'.
  10194. `@thistitle'
  10195.      Expands to the name of the document, as specified by the
  10196.      `@settitle' command.
  10197. `@thisfile'
  10198.      For `@include' files only: expands to the name of the current
  10199.      `@include' file.  If the current Texinfo source file is not an
  10200.      `@include' file, this command has no effect.  This command does
  10201.      *not* provide the name of the current Texinfo source file unless
  10202.      it is an `@include' file.  (*Note Include Files::, for more
  10203.      information about `@include' files.)
  10204. You can also use the `@today{}' command, which expands to the current
  10205. date, in `1 Jan 1900' format.
  10206.    Other @-commands and text are printed in a header or footer just as
  10207. if they were in the body of a page.  It is useful to incorporate text,
  10208. particularly when you are writing drafts:
  10209.      @iftex
  10210.      @headings off
  10211.      @everyheading @emph{Draft!} @| @thispage @| @thischapter
  10212.      @everyfooting @| @| Version: 0.27: @today{}
  10213.      @end iftex
  10214.    Beware of overlong titles: they may overlap another part of the
  10215. header or footer and blot it out.
  10216. File: texi.info,  Node: Catching Mistakes,  Next: Refilling Paragraphs,  Prev: Headings,  Up: Top
  10217. Formatting Mistakes
  10218. *******************
  10219.    Besides mistakes in the content of your documentation, there are two
  10220. kinds of mistake you can make with Texinfo:  you can make mistakes with
  10221. @-commands, and you can make mistakes with the structure of the nodes
  10222. and chapters.
  10223.    Emacs has two tools for catching the @-command mistakes and two for
  10224. catching structuring mistakes.
  10225.    For finding problems with @-commands, you can run TeX or a region
  10226. formatting command on the region that has a problem; indeed, you can
  10227. run these commands on each region as you write it.
  10228.    For finding problems with the structure of nodes and chapters, you
  10229. can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
  10230. command and you can use the `M-x Info-validate' command.
  10231. * Menu:
  10232. * makeinfo preferred::          `makeinfo' finds errors.
  10233. * Debugging with Info::         How to catch errors with Info formatting.
  10234. * Debugging with TeX::          How to catch errors with TeX formatting.
  10235. * Using texinfo-show-structure::  How to use `texinfo-show-structure'.
  10236. * Using occur::                 How to list all lines containing a pattern.
  10237. * Running Info-Validate::       How to find badly referenced nodes.
  10238. File: texi.info,  Node: makeinfo preferred,  Next: Debugging with Info,  Up: Catching Mistakes
  10239. `makeinfo' Find Errors
  10240. ======================
  10241.    The `makeinfo' program does an excellent job of catching errors and
  10242. reporting them--far better than either the `texinfo-format-region' or
  10243. the `texinfo-format-buffer' command.  In addition, the various
  10244. functions for automatically creating and updating node pointers and
  10245. menus remove many opportunities for human error.
  10246.    If you can, use the updating commands to create and insert pointers
  10247. and menus.  These prevent many errors.  Then use `makeinfo' (or its
  10248. Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
  10249. to format your file and check for other errors.  This is the best way
  10250. to work with Texinfo.  But if you cannot use `makeinfo', or your
  10251. problem is very puzzling, then you may want to use the tools described
  10252. in this appendix.
  10253. File: texi.info,  Node: Debugging with Info,  Next: Debugging with TeX,  Prev: makeinfo preferred,  Up: Catching Mistakes
  10254. Catching Errors with Info Formatting
  10255. ====================================
  10256.    After you have written part of a Texinfo file, you can use the
  10257. `texinfo-format-region' or the `makeinfo-region' command to see whether
  10258. the region formats properly.
  10259.    Most likely, however, you are reading this section because for some
  10260. reason you cannot use the `makeinfo-region' command; therefore, the
  10261. rest of this section presumes that you are using
  10262. `texinfo-format-region'.
  10263.    If you make a mistake with an @-command, `texinfo-format-region'
  10264. will stop processing at or after the error and display an error
  10265. message.  To see where in the buffer the error occurred, switch to the
  10266. `*Info Region*' buffer; the cursor will be in a position that is after
  10267. the location of the error.  Also, the text will not be formatted after
  10268. the place where the error occurred (or more precisely, where it was
  10269. detected).
  10270.    For example, if you accidentally end a menu with the command `@end
  10271. menus' with an `s' on the end, instead of with `@end menu', you will
  10272. see an error message that says:
  10273.      @end menus is not handled by texinfo
  10274. The cursor will stop at the point in the buffer where the error occurs,
  10275. or not long after it.  The buffer will look like this:
  10276.      ---------- Buffer: *Info Region* ----------
  10277.      * Menu:
  10278.      
  10279.      * Using texinfo-show-structure::  How to use
  10280.                                        `texinfo-show-structure'
  10281.                                        to catch mistakes.
  10282.      * Running Info-Validate::         How to check for
  10283.                                        unreferenced nodes.
  10284.      @end menus
  10285.      -!-
  10286.      ---------- Buffer: *Info Region* ----------
  10287.    The `texinfo-format-region' command sometimes provides slightly odd
  10288. error messages.  For example, the following cross reference fails to
  10289. format:
  10290.      (@xref{Catching Mistakes, for more info.)
  10291. In this case, `texinfo-format-region' detects the missing closing brace
  10292. but displays a message that says `Unbalanced parentheses' rather than
  10293. `Unbalanced braces'.  This is because the formatting command looks for
  10294. mismatches between braces as if they were parentheses.
  10295.    Sometimes `texinfo-format-region' fails to detect mistakes.  For
  10296. example, in the following, the closing brace is swapped with the
  10297. closing parenthesis:
  10298.      (@xref{Catching Mistakes), for more info.}
  10299. Formatting produces:
  10300.      (*Note for more info.: Catching Mistakes)
  10301.    The only way for you to detect this error is to realize that the
  10302. reference should have looked like this:
  10303.      (*Note Catching Mistakes::, for more info.)
  10304.    Incidentally, if you are reading this node in Info and type `f RET'
  10305. (`Info-follow-reference'), you will generate an error message that says:
  10306.      No such node: "Catching Mistakes) The only way ...
  10307. This is because Info perceives the example of the error as the first
  10308. cross reference in this node and if you type a RET immediately after
  10309. typing the Info `f' command, Info will attempt to go to the referenced
  10310. node.  If you type `f catch TAB RET', Info will complete the node name
  10311. of the correctly written example and take you to the `Catching
  10312. Mistakes' node.  (If you try this, you can return from the `Catching
  10313. Mistakes' node by typing `l' (`Info-last').)
  10314.